@slock-ai/daemon 0.54.2 → 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
@@ -46,10 +72,430 @@ function readCliVersion(baseUrl = import.meta.url) {
   );
 }
 
+// src/proxy.ts
+import { ProxyAgent } from "undici";
+var fetchDispatcherCache = /* @__PURE__ */ new Map();
+function getDefaultPort(protocol) {
+  switch (protocol) {
+    case "https:":
+      return "443";
+    case "http:":
+      return "80";
+    default:
+      return "";
+  }
+}
+function hostMatchesNoProxyEntry(hostname3, ruleHost) {
+  if (!ruleHost) return false;
+  const normalizedRule = ruleHost.replace(/^\*\./, ".").replace(/^\./, "").toLowerCase();
+  const normalizedHost = hostname3.toLowerCase();
+  return normalizedHost === normalizedRule || normalizedHost.endsWith(`.${normalizedRule}`);
+}
+function getProxyUrlForTarget(targetUrl, env) {
+  const protocol = new URL(targetUrl).protocol;
+  switch (protocol) {
+    case "https:":
+      return env.HTTPS_PROXY || env.https_proxy || env.ALL_PROXY || env.all_proxy;
+    case "http:":
+      return env.HTTP_PROXY || env.http_proxy || env.ALL_PROXY || env.all_proxy;
+    default:
+      return env.ALL_PROXY || env.all_proxy;
+  }
+}
+function shouldBypassProxy(targetUrl, env) {
+  const rawNoProxy = env.NO_PROXY || env.no_proxy;
+  if (!rawNoProxy) return false;
+  const url2 = new URL(targetUrl);
+  const hostname3 = url2.hostname.toLowerCase();
+  const port = url2.port || getDefaultPort(url2.protocol);
+  return rawNoProxy.split(",").map((entry) => entry.trim()).filter(Boolean).some((entry) => {
+    if (entry === "*") return true;
+    const [ruleHost, rulePort] = entry.split(":", 2);
+    if (rulePort && rulePort !== port) return false;
+    return hostMatchesNoProxyEntry(hostname3, ruleHost);
+  });
+}
+function buildFetchDispatcher(targetUrl, env = process.env) {
+  const proxyUrl = getProxyUrlForTarget(targetUrl, env);
+  if (!proxyUrl) return void 0;
+  if (shouldBypassProxy(targetUrl, env)) return void 0;
+  const cached2 = fetchDispatcherCache.get(proxyUrl);
+  if (cached2) return cached2;
+  const dispatcher = new ProxyAgent(proxyUrl);
+  fetchDispatcherCache.set(proxyUrl, dispatcher);
+  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) {
+    this.ctx = ctx;
+  }
+  usesAgentApiSurface() {
+    return this.ctx.clientMode === "managed-runner" || this.ctx.clientMode === "self-hosted-runner";
+  }
+  rewriteAgentCredentialPath(pathname) {
+    if (!this.usesAgentApiSurface()) return pathname;
+    const attachmentDownload = /^\/api\/attachments\/([^/?]+)(.*)$/.exec(pathname);
+    if (attachmentDownload) {
+      return `/internal/agent-api/attachments/${attachmentDownload[1]}${attachmentDownload[2] ?? ""}`;
+    }
+    const agentPrefix = `/internal/agent/${encodeURIComponent(this.ctx.agentId)}`;
+    if (!pathname.startsWith(agentPrefix)) return pathname;
+    const suffix = pathname.slice(agentPrefix.length);
+    if (suffix === "/server") return "/internal/agent-api/server";
+    if (suffix === "/send") return "/internal/agent-api/send";
+    if (suffix.startsWith("/history")) return `/internal/agent-api/history${suffix.slice("/history".length)}`;
+    if (suffix.startsWith("/search")) return `/internal/agent-api/search${suffix.slice("/search".length)}`;
+    if (suffix.startsWith("/channel-members")) return `/internal/agent-api/channel-members${suffix.slice("/channel-members".length)}`;
+    if (suffix === "/knowledge" || suffix.startsWith("/knowledge?")) {
+      return `/internal/agent-api/knowledge${suffix.slice("/knowledge".length)}`;
+    }
+    if (suffix === "/profile" || suffix.startsWith("/profile/")) return `/internal/agent-api${suffix}`;
+    if (suffix === "/integrations" || suffix.startsWith("/integrations/")) return `/internal/agent-api${suffix}`;
+    if (suffix === "/upload") return "/internal/agent-api/upload";
+    if (suffix === "/resolve-channel") return "/internal/agent-api/resolve-channel";
+    if (suffix === "/threads/unfollow") return "/internal/agent-api/threads/unfollow";
+    if (suffix === "/prepare-action") return "/internal/agent-api/prepare-action";
+    if (suffix === "/tasks" || suffix.startsWith("/tasks?") || suffix.startsWith("/tasks/")) {
+      return `/internal/agent-api${suffix}`;
+    }
+    if (suffix === "/reminders" || suffix.startsWith("/reminders?") || suffix.startsWith("/reminders/")) {
+      return `/internal/agent-api${suffix}`;
+    }
+    if (suffix === "/receive" || suffix.startsWith("/receive?")) {
+      return "/internal/agent-api/events?since=latest";
+    }
+    const reaction = /^\/messages\/([^/]+)\/reactions$/.exec(suffix);
+    if (reaction) {
+      return `/internal/agent-api/messages/${reaction[1]}/reactions`;
+    }
+    const channelMembership = /^\/channels\/([^/]+)\/(join|leave)$/.exec(suffix);
+    if (channelMembership) {
+      return `/internal/agent-api/channels/${channelMembership[1]}/${channelMembership[2]}`;
+    }
+    return pathname;
+  }
+  normalizeAgentCredentialResponse(pathname, data) {
+    if (!this.usesAgentApiSurface()) return data;
+    if (!pathname.includes("/internal/agent-api/events")) return data;
+    const value = data;
+    if (!Array.isArray(value.events)) return data;
+    return { ...data, messages: value.events };
+  }
+  buildAuthHeaders() {
+    const headers = {
+      "Authorization": `Bearer ${this.ctx.token}`,
+      "X-Agent-Id": this.ctx.agentId,
+      "X-Slock-Client": "cli"
+    };
+    if (this.ctx.serverId) headers["X-Server-Id"] = this.ctx.serverId;
+    return headers;
+  }
+  async parseJsonResponse(res) {
+    let data = null;
+    let error48 = null;
+    let errorCode2 = null;
+    const contentType = res.headers.get("content-type") ?? "";
+    if (contentType.includes("application/json")) {
+      let parseFailed = false;
+      const parsed = await res.json().catch(() => {
+        parseFailed = true;
+        return null;
+      });
+      if (parseFailed) {
+        return {
+          ok: false,
+          status: res.status,
+          data: null,
+          error: `Invalid JSON response from server/proxy (HTTP ${res.status})`,
+          errorCode: "INVALID_JSON_RESPONSE"
+        };
+      }
+      if (res.ok) {
+        data = parsed;
+      } else {
+        const body = parsed;
+        if (res.status === 403 && body?.requiredScope) {
+          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}`;
+          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: 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);
+    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.toString());
+    const init = {
+      method,
+      headers,
+      body: body === void 0 ? void 0 : JSON.stringify(body)
+    };
+    if (dispatcher) init.dispatcher = dispatcher;
+    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);
+    }
+    return parsed;
+  }
+  // Multipart upload. Caller builds the FormData (file part + any text fields).
+  // Content-Type intentionally omitted so fetch sets the correct multipart
+  // boundary itself.
+  async requestMultipart(method, pathname, form) {
+    pathname = this.rewriteAgentCredentialPath(pathname);
+    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(",");
+    }
+    const init = {
+      method,
+      headers,
+      body: form
+    };
+    if (dispatcher) init.dispatcher = dispatcher;
+    const res = await this.fetchWithTransportTrace(url2, pathname, init);
+    return this.parseJsonResponse(res);
+  }
+  // Returns the raw Response so the caller can stream / save the body.
+  // For non-JSON downloads (binary attachments). Caller is responsible for
+  // 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);
+    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(",");
+    }
+    const init = {
+      method,
+      headers,
+      redirect: "follow"
+    };
+    if (dispatcher) init.dispatcher = dispatcher;
+    const res = await this.fetchWithTransportTrace(url2, pathname, init);
+    let error48 = null;
+    if (!res.ok) {
+      const contentType = res.headers.get("content-type") ?? "";
+      if (contentType.includes("application/json")) {
+        const parsed = await res.json().catch(() => null);
+        error48 = parsed?.error ?? `HTTP ${res.status}`;
+      } else {
+        error48 = `HTTP ${res.status}`;
+      }
+    }
+    return { ok: res.ok, status: res.status, response: res, error: error48 };
+  }
+};
+
 // 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",
@@ -72,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);
@@ -216,29 +662,137 @@ function loadAgentContext(env = process.env) {
   );
 }
 
-// src/commands/auth/whoami.ts
-function registerWhoamiCommand(parent) {
-  parent.command("whoami").description("Print the agent context resolved from env (token value redacted)").action(() => {
-    let ctx;
+// src/core/io.ts
+function defaultCliIo() {
+  return {
+    stdin: process.stdin,
+    stdout: process.stdout,
+    stderr: process.stderr
+  };
+}
+
+// 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 createCommandContext(options = {}) {
+  const io = options.io ?? defaultCliIo();
+  const env = options.env ?? process.env;
+  const loadContext = options.loadAgentContext ?? loadAgentContext;
+  const createApiClient = options.createApiClient ?? ((agentContext) => new ApiClient(agentContext));
+  return {
+    io,
+    env,
+    loadAgentContext() {
+      try {
+        return loadContext(env);
+      } catch (err) {
+        if (err instanceof AgentBootstrapError) {
+          throw new CliError({
+            code: err.code,
+            message: err.message,
+            cause: err,
+            suggestedNextAction: bootstrapSuggestedNextAction(err.code)
+          });
+        }
+        throw err;
+      }
+    },
+    createApiClient
+  };
+}
+
+// src/core/renderer.ts
+function renderError(io, err) {
+  io.stderr.write(`Error: ${err.message}
+`);
+  io.stderr.write(`Code: ${err.code}
+`);
+  if (err.suggestedNextAction) {
+    io.stderr.write(`Next action: ${err.suggestedNextAction}
+`);
+  }
+}
+function writeText(io, text) {
+  io.stdout.write(text);
+}
+function writeJson(io, payload) {
+  io.stdout.write(`${JSON.stringify(payload)}
+`);
+}
+
+// src/core/command.ts
+function defineCommand(spec, handler) {
+  return { spec, handler };
+}
+function registerCliCommand(parent, command, runtimeOptions = {}) {
+  const child = parent.command(command.spec.name).description(command.spec.description);
+  for (const arg of command.spec.arguments ?? []) {
+    child.argument(arg);
+  }
+  for (const option of command.spec.options ?? []) {
+    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 {
-      ctx = loadAgentContext();
+      await command.handler(ctx, ...args);
     } catch (err) {
-      if (err instanceof AgentBootstrapError) fail(err.code, err.message);
-      throw err;
+      const cliError2 = toCliError(err);
+      renderError(ctx.io, cliError2);
+      throw new CliExit(cliError2.exitCode);
     }
-    emit({
+  });
+}
+
+// src/commands/auth/whoami.ts
+var whoamiCommand = defineCommand(
+  {
+    name: "whoami",
+    description: "Print the agent context resolved from env (token value redacted)"
+  },
+  (ctx) => {
+    const agentContext = ctx.loadAgentContext();
+    writeJson(ctx.io, {
       ok: true,
       data: {
-        agentId: ctx.agentId,
-        serverUrl: ctx.serverUrl,
-        serverId: ctx.serverId,
-        clientMode: ctx.clientMode,
-        secretSource: ctx.secretSource,
-        ...ctx.profileSlug ? { profileSlug: ctx.profileSlug } : {},
-        ...ctx.profileCredentialPath ? { profileCredentialPath: ctx.profileCredentialPath } : {}
+        agentId: agentContext.agentId,
+        serverUrl: agentContext.serverUrl,
+        serverId: agentContext.serverId,
+        clientMode: agentContext.clientMode,
+        secretSource: agentContext.secretSource,
+        ...agentContext.profileSlug ? { profileSlug: agentContext.profileSlug } : {},
+        ...agentContext.profileCredentialPath ? { profileCredentialPath: agentContext.profileCredentialPath } : {}
       }
     });
-  });
+  }
+);
+function registerWhoamiCommand(parent, runtimeOptions) {
+  registerCliCommand(parent, whoamiCommand, runtimeOptions);
 }
 
 // src/commands/agent/list.ts
@@ -355,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).
 `
           );
@@ -373,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;
     }
@@ -393,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}).`
       );
@@ -402,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,
@@ -411,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}.`,
         {
@@ -446,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).
 `
           );
@@ -454,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;
     }
@@ -473,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
@@ -481,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."
       );
@@ -506,7 +1087,7 @@ function registerAgentLoginCommand(parent) {
       ) + "\n",
       { mode: 384 }
     );
-    emit({
+    writeJson(ctx.io, {
       ok: true,
       data: {
         agentId: minted.agentId,
@@ -518,7 +1099,10 @@ function registerAgentLoginCommand(parent) {
         credentialPath
       }
     });
-  });
+  }
+);
+function registerAgentLoginCommand(parent, runtimeOptions = {}) {
+  registerCliCommand(parent, agentLoginCommand, runtimeOptions);
 }
 async function safeJson2(res) {
   try {
@@ -575,32 +1159,56 @@ function describeMintError(code, serverUrl) {
   return void 0;
 }
 
+// ../shared/src/slockRefs.ts
+var SLOCK_REF_CHANNEL_NAME_PATTERN = String.raw`[\p{L}\p{N}_-]+`;
+var SLOCK_REF_USER_NAME_PATTERN = SLOCK_REF_CHANNEL_NAME_PATTERN;
+var SLOCK_REF_DM_PEER_PATTERN = String.raw`[\w-]+`;
+var SLOCK_REF_THREAD_SHORT_ID_PATTERN = String.raw`[\da-f]{6,8}`;
+var SLOCK_REF_MESSAGE_ID_PATTERN = String.raw`[A-Za-z0-9][A-Za-z0-9-]{1,63}`;
+var SLOCK_REF_TASK_NUMBER_PATTERN = String.raw`[1-9]\d*`;
+var USER_RE = new RegExp(String.raw`^@(${SLOCK_REF_USER_NAME_PATTERN})$`, "u");
+var CHANNEL_RE = new RegExp(String.raw`^#(${SLOCK_REF_CHANNEL_NAME_PATTERN})$`, "u");
+var CHANNEL_THREAD_RE = new RegExp(
+  String.raw`^#(${SLOCK_REF_CHANNEL_NAME_PATTERN}):(${SLOCK_REF_THREAD_SHORT_ID_PATTERN})$`,
+  "iu"
+);
+var DM_RE = new RegExp(String.raw`^dm:@(${SLOCK_REF_DM_PEER_PATTERN})$`, "iu");
+var DM_THREAD_RE = new RegExp(
+  String.raw`^dm:@(${SLOCK_REF_DM_PEER_PATTERN}):(${SLOCK_REF_THREAD_SHORT_ID_PATTERN})$`,
+  "iu"
+);
+var TASK_RE = new RegExp(String.raw`^task\s+#(${SLOCK_REF_TASK_NUMBER_PATTERN})$`, "iu");
+var CHANNEL_MESSAGE_RE = new RegExp(
+  String.raw`^#(${SLOCK_REF_CHANNEL_NAME_PATTERN})(?::(${SLOCK_REF_THREAD_SHORT_ID_PATTERN}))?\s+msg=(${SLOCK_REF_MESSAGE_ID_PATTERN})$`,
+  "iu"
+);
+
 // ../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`);
@@ -640,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("");
@@ -1428,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);
@@ -1814,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;
   });
 }
@@ -2001,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) {
@@ -2011,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;
@@ -2043,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")
@@ -14021,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}`);
     }
@@ -14634,234 +15242,6 @@ var DISPLAY_PLAN_CONFIG = {
   }
 };
 
-// src/proxy.ts
-import { ProxyAgent } from "undici";
-var fetchDispatcherCache = /* @__PURE__ */ new Map();
-function getDefaultPort(protocol) {
-  switch (protocol) {
-    case "https:":
-      return "443";
-    case "http:":
-      return "80";
-    default:
-      return "";
-  }
-}
-function hostMatchesNoProxyEntry(hostname3, ruleHost) {
-  if (!ruleHost) return false;
-  const normalizedRule = ruleHost.replace(/^\*\./, ".").replace(/^\./, "").toLowerCase();
-  const normalizedHost = hostname3.toLowerCase();
-  return normalizedHost === normalizedRule || normalizedHost.endsWith(`.${normalizedRule}`);
-}
-function getProxyUrlForTarget(targetUrl, env) {
-  const protocol = new URL(targetUrl).protocol;
-  switch (protocol) {
-    case "https:":
-      return env.HTTPS_PROXY || env.https_proxy || env.ALL_PROXY || env.all_proxy;
-    case "http:":
-      return env.HTTP_PROXY || env.http_proxy || env.ALL_PROXY || env.all_proxy;
-    default:
-      return env.ALL_PROXY || env.all_proxy;
-  }
-}
-function shouldBypassProxy(targetUrl, env) {
-  const rawNoProxy = env.NO_PROXY || env.no_proxy;
-  if (!rawNoProxy) return false;
-  const url2 = new URL(targetUrl);
-  const hostname3 = url2.hostname.toLowerCase();
-  const port = url2.port || getDefaultPort(url2.protocol);
-  return rawNoProxy.split(",").map((entry) => entry.trim()).filter(Boolean).some((entry) => {
-    if (entry === "*") return true;
-    const [ruleHost, rulePort] = entry.split(":", 2);
-    if (rulePort && rulePort !== port) return false;
-    return hostMatchesNoProxyEntry(hostname3, ruleHost);
-  });
-}
-function buildFetchDispatcher(targetUrl, env = process.env) {
-  const proxyUrl = getProxyUrlForTarget(targetUrl, env);
-  if (!proxyUrl) return void 0;
-  if (shouldBypassProxy(targetUrl, env)) return void 0;
-  const cached2 = fetchDispatcherCache.get(proxyUrl);
-  if (cached2) return cached2;
-  const dispatcher = new ProxyAgent(proxyUrl);
-  fetchDispatcherCache.set(proxyUrl, dispatcher);
-  return dispatcher;
-}
-
-// src/client.ts
-var ApiClient = class {
-  constructor(ctx) {
-    this.ctx = ctx;
-  }
-  usesAgentApiSurface() {
-    return this.ctx.clientMode === "managed-runner" || this.ctx.clientMode === "self-hosted-runner";
-  }
-  rewriteAgentCredentialPath(pathname) {
-    if (!this.usesAgentApiSurface()) return pathname;
-    const attachmentDownload = /^\/api\/attachments\/([^/?]+)(.*)$/.exec(pathname);
-    if (attachmentDownload) {
-      return `/internal/agent-api/attachments/${attachmentDownload[1]}${attachmentDownload[2] ?? ""}`;
-    }
-    const agentPrefix = `/internal/agent/${encodeURIComponent(this.ctx.agentId)}`;
-    if (!pathname.startsWith(agentPrefix)) return pathname;
-    const suffix = pathname.slice(agentPrefix.length);
-    if (suffix === "/server") return "/internal/agent-api/server";
-    if (suffix === "/send") return "/internal/agent-api/send";
-    if (suffix.startsWith("/history")) return `/internal/agent-api/history${suffix.slice("/history".length)}`;
-    if (suffix.startsWith("/search")) return `/internal/agent-api/search${suffix.slice("/search".length)}`;
-    if (suffix.startsWith("/channel-members")) return `/internal/agent-api/channel-members${suffix.slice("/channel-members".length)}`;
-    if (suffix === "/profile" || suffix.startsWith("/profile/")) return `/internal/agent-api${suffix}`;
-    if (suffix === "/integrations" || suffix.startsWith("/integrations/")) return `/internal/agent-api${suffix}`;
-    if (suffix === "/upload") return "/internal/agent-api/upload";
-    if (suffix === "/resolve-channel") return "/internal/agent-api/resolve-channel";
-    if (suffix === "/threads/unfollow") return "/internal/agent-api/threads/unfollow";
-    if (suffix === "/prepare-action") return "/internal/agent-api/prepare-action";
-    if (suffix === "/tasks" || suffix.startsWith("/tasks?") || suffix.startsWith("/tasks/")) {
-      return `/internal/agent-api${suffix}`;
-    }
-    if (suffix === "/reminders" || suffix.startsWith("/reminders?") || suffix.startsWith("/reminders/")) {
-      return `/internal/agent-api${suffix}`;
-    }
-    if (suffix === "/receive" || suffix.startsWith("/receive?")) {
-      return "/internal/agent-api/events?since=latest";
-    }
-    const reaction = /^\/messages\/([^/]+)\/reactions$/.exec(suffix);
-    if (reaction) {
-      return `/internal/agent-api/messages/${reaction[1]}/reactions`;
-    }
-    const channelMembership = /^\/channels\/([^/]+)\/(join|leave)$/.exec(suffix);
-    if (channelMembership) {
-      return `/internal/agent-api/channels/${channelMembership[1]}/${channelMembership[2]}`;
-    }
-    return pathname;
-  }
-  normalizeAgentCredentialResponse(pathname, data) {
-    if (!this.usesAgentApiSurface()) return data;
-    if (!pathname.includes("/internal/agent-api/events")) return data;
-    const value = data;
-    if (!Array.isArray(value.events)) return data;
-    return { ...data, messages: value.events };
-  }
-  buildAuthHeaders() {
-    const headers = {
-      "Authorization": `Bearer ${this.ctx.token}`,
-      "X-Agent-Id": this.ctx.agentId,
-      "X-Slock-Client": "cli"
-    };
-    if (this.ctx.serverId) headers["X-Server-Id"] = this.ctx.serverId;
-    return headers;
-  }
-  async parseJsonResponse(res) {
-    let data = null;
-    let error48 = null;
-    let errorCode = null;
-    const contentType = res.headers.get("content-type") ?? "";
-    if (contentType.includes("application/json")) {
-      let parseFailed = false;
-      const parsed = await res.json().catch(() => {
-        parseFailed = true;
-        return null;
-      });
-      if (parseFailed) {
-        return {
-          ok: false,
-          status: res.status,
-          data: null,
-          error: `Invalid JSON response from server/proxy (HTTP ${res.status})`,
-          errorCode: "INVALID_JSON_RESPONSE"
-        };
-      }
-      if (res.ok) {
-        data = parsed;
-      } else {
-        const body = parsed;
-        if (res.status === 403 && body?.requiredScope) {
-          errorCode = "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;
-        }
-      }
-    } else if (!res.ok) {
-      error48 = `HTTP ${res.status}`;
-    }
-    return { ok: res.ok, status: res.status, data, error: error48, errorCode };
-  }
-  async request(method, pathname, body) {
-    pathname = this.rewriteAgentCredentialPath(pathname);
-    const url2 = new URL(pathname, this.ctx.serverUrl).toString();
-    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 init = {
-      method,
-      headers,
-      body: body === void 0 ? void 0 : JSON.stringify(body)
-    };
-    if (dispatcher) init.dispatcher = dispatcher;
-    const res = await fetch(url2, init);
-    const parsed = await this.parseJsonResponse(res);
-    if (parsed.ok && parsed.data !== null) {
-      parsed.data = this.normalizeAgentCredentialResponse(pathname, parsed.data);
-    }
-    return parsed;
-  }
-  // Multipart upload. Caller builds the FormData (file part + any text fields).
-  // Content-Type intentionally omitted so fetch sets the correct multipart
-  // 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 headers = this.buildAuthHeaders();
-    if (this.ctx.activeCapabilities && this.ctx.activeCapabilities.length > 0) {
-      headers["X-Slock-Agent-Active-Capabilities"] = this.ctx.activeCapabilities.join(",");
-    }
-    const init = {
-      method,
-      headers,
-      body: form
-    };
-    if (dispatcher) init.dispatcher = dispatcher;
-    const res = await fetch(url2, init);
-    return this.parseJsonResponse(res);
-  }
-  // Returns the raw Response so the caller can stream / save the body.
-  // For non-JSON downloads (binary attachments). Caller is responsible for
-  // 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 headers = this.buildAuthHeaders();
-    if (this.ctx.activeCapabilities && this.ctx.activeCapabilities.length > 0) {
-      headers["X-Slock-Agent-Active-Capabilities"] = this.ctx.activeCapabilities.join(",");
-    }
-    const init = {
-      method,
-      headers,
-      redirect: "follow"
-    };
-    if (dispatcher) init.dispatcher = dispatcher;
-    const res = await fetch(url2, init);
-    let error48 = null;
-    if (!res.ok) {
-      const contentType = res.headers.get("content-type") ?? "";
-      if (contentType.includes("application/json")) {
-        const parsed = await res.json().catch(() => null);
-        error48 = parsed?.error ?? `HTTP ${res.status}`;
-      } else {
-        error48 = `HTTP ${res.status}`;
-      }
-    }
-    return { ok: res.ok, status: res.status, response: res, error: error48 };
-  }
-};
-
 // src/commands/action/prepare.ts
 var ACTION_HEREDOC_DELIMITER = "SLOCKACTION";
 var PrepareActionInputError = class extends Error {
@@ -14905,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
@@ -15053,29 +15441,38 @@ function formatChannelMembers(data) {
 }
 
 // src/commands/channel/members.ts
-function registerChannelMembersCommand(parent) {
-  parent.command("members").description("List agents and humans who are members of a channel, DM, or thread").argument("<target>", "Channel / DM / thread target, e.g. #proj-runtime, dm:@alice, #proj-runtime:abcd1234").action(async (target) => {
-    let ctx;
-    try {
-      ctx = loadAgentContext();
-    } catch (err) {
-      if (err instanceof AgentBootstrapError) fail(err.code, err.message);
-      throw err;
-    }
-    const client = new ApiClient(ctx);
+var channelMembersCommand = defineCommand(
+  {
+    name: "members",
+    description: "List agents and humans who are members of a channel, DM, or thread",
+    arguments: ["<target>"]
+  },
+  async (ctx, target) => {
     const channel = String(target || "").trim();
-    if (!channel) fail("MEMBERS_FAILED", "target is required");
+    if (!channel) {
+      throw new CliError({
+        code: "INVALID_ARG",
+        message: "target is required"
+      });
+    }
+    const agentContext = ctx.loadAgentContext();
+    const client = ctx.createApiClient(agentContext);
     const encoded = encodeURIComponent(channel);
     const res = await client.request(
       "GET",
-      `/internal/agent/${encodeURIComponent(ctx.agentId)}/channel-members?channel=${encoded}`
+      `/internal/agent/${encodeURIComponent(agentContext.agentId)}/channel-members?channel=${encoded}`
     );
     if (!res.ok) {
-      const code = res.status >= 500 ? "SERVER_5XX" : "MEMBERS_FAILED";
-      fail(code, res.error ?? `HTTP ${res.status}`);
+      throw new CliError({
+        code: res.status >= 500 ? "SERVER_5XX" : "MEMBERS_FAILED",
+        message: res.error ?? `HTTP ${res.status}`
+      });
     }
-    process.stdout.write(formatChannelMembers(res.data));
-  });
+    writeText(ctx.io, formatChannelMembers(res.data));
+  }
+);
+function registerChannelMembersCommand(parent, runtimeOptions) {
+  registerCliCommand(parent, channelMembersCommand, runtimeOptions);
 }
 
 // src/commands/channel/leave.ts
@@ -15091,46 +15488,64 @@ function formatLeaveChannelResult(target) {
 function formatAlreadyNotJoined(target) {
   return `Already not joined in ${target}.`;
 }
-function registerChannelLeaveCommand(parent) {
-  parent.command("leave").description("Leave a regular channel you have joined").requiredOption("--target <target>", "Regular channel to leave, e.g. '#engineering'").action(async (opts) => {
-    const channelName = parseRegularChannelTarget(opts.target);
+var channelLeaveCommand = defineCommand(
+  {
+    name: "leave",
+    description: "Leave a regular channel you have joined",
+    options: [
+      {
+        flags: "--target <target>",
+        description: "Regular channel to leave, e.g. '#engineering'"
+      }
+    ]
+  },
+  async (ctx, opts) => {
+    const target = opts.target ?? "";
+    const channelName = parseRegularChannelTarget(target);
     if (!channelName) {
-      fail("INVALID_TARGET", "Target must be a regular channel in the form '#channel-name'. DMs and thread targets are not supported.");
-    }
-    let ctx;
-    try {
-      ctx = loadAgentContext();
-    } catch (err) {
-      if (err instanceof AgentBootstrapError) fail(err.code, err.message);
-      throw err;
+      throw new CliError({
+        code: "INVALID_TARGET",
+        message: "Target must be a regular channel in the form '#channel-name'. DMs and thread targets are not supported."
+      });
     }
-    const client = new ApiClient(ctx);
+    const agentContext = ctx.loadAgentContext();
+    const client = ctx.createApiClient(agentContext);
     const infoRes = await client.request(
       "GET",
-      `/internal/agent/${encodeURIComponent(ctx.agentId)}/server`
+      `/internal/agent/${encodeURIComponent(agentContext.agentId)}/server`
     );
     if (!infoRes.ok) {
-      const code = infoRes.status >= 500 ? "SERVER_5XX" : "INFO_FAILED";
-      fail(code, infoRes.error ?? `HTTP ${infoRes.status}`);
+      throw new CliError({
+        code: infoRes.status >= 500 ? "SERVER_5XX" : "INFO_FAILED",
+        message: infoRes.error ?? `HTTP ${infoRes.status}`
+      });
     }
     const channel = (infoRes.data?.channels ?? []).find((candidate) => candidate.name === channelName);
     if (!channel) {
-      fail("NOT_FOUND", `Channel not found: ${opts.target}`);
+      throw new CliError({
+        code: "NOT_FOUND",
+        message: `Channel not found: ${target}`
+      });
     }
     if (!channel.joined) {
-      process.stdout.write(formatAlreadyNotJoined(opts.target) + "\n");
+      writeText(ctx.io, formatAlreadyNotJoined(target) + "\n");
       return;
     }
     const leaveRes = await client.request(
       "POST",
-      `/internal/agent/${encodeURIComponent(ctx.agentId)}/channels/${encodeURIComponent(channel.id)}/leave`
+      `/internal/agent/${encodeURIComponent(agentContext.agentId)}/channels/${encodeURIComponent(channel.id)}/leave`
     );
     if (!leaveRes.ok) {
-      const code = leaveRes.status >= 500 ? "SERVER_5XX" : "LEAVE_FAILED";
-      fail(code, leaveRes.error ?? `HTTP ${leaveRes.status}`);
+      throw new CliError({
+        code: leaveRes.status >= 500 ? "SERVER_5XX" : "LEAVE_FAILED",
+        message: leaveRes.error ?? `HTTP ${leaveRes.status}`
+      });
     }
-    process.stdout.write(formatLeaveChannelResult(opts.target) + "\n");
-  });
+    writeText(ctx.io, formatLeaveChannelResult(target) + "\n");
+  }
+);
+function registerChannelLeaveCommand(parent, runtimeOptions) {
+  registerCliCommand(parent, channelLeaveCommand, runtimeOptions);
 }
 
 // src/commands/channel/join.ts
@@ -15140,76 +15555,177 @@ function formatJoinChannelResult(target) {
 function formatAlreadyJoined(target) {
   return `Already joined ${target}.`;
 }
-function registerChannelJoinCommand(parent) {
-  parent.command("join").description("Join a visible public channel").requiredOption("--target <target>", "Regular channel to join, e.g. '#engineering'").action(async (opts) => {
-    const channelName = parseRegularChannelTarget(opts.target);
+var channelJoinCommand = defineCommand(
+  {
+    name: "join",
+    description: "Join a visible public channel",
+    options: [
+      {
+        flags: "--target <target>",
+        description: "Regular channel to join, e.g. '#engineering'"
+      }
+    ]
+  },
+  async (ctx, opts) => {
+    const target = opts.target ?? "";
+    const channelName = parseRegularChannelTarget(target);
     if (!channelName) {
-      fail("INVALID_TARGET", "Target must be a regular channel in the form '#channel-name'. DMs and thread targets are not supported.");
-    }
-    let ctx;
-    try {
-      ctx = loadAgentContext();
-    } catch (err) {
-      if (err instanceof AgentBootstrapError) fail(err.code, err.message);
-      throw err;
+      throw new CliError({
+        code: "INVALID_TARGET",
+        message: "Target must be a regular channel in the form '#channel-name'. DMs and thread targets are not supported."
+      });
     }
-    const client = new ApiClient(ctx);
+    const agentContext = ctx.loadAgentContext();
+    const client = ctx.createApiClient(agentContext);
     const infoRes = await client.request(
       "GET",
-      `/internal/agent/${encodeURIComponent(ctx.agentId)}/server`
+      `/internal/agent/${encodeURIComponent(agentContext.agentId)}/server`
     );
     if (!infoRes.ok) {
-      const code = infoRes.status >= 500 ? "SERVER_5XX" : "INFO_FAILED";
-      fail(code, infoRes.error ?? `HTTP ${infoRes.status}`);
+      throw new CliError({
+        code: infoRes.status >= 500 ? "SERVER_5XX" : "INFO_FAILED",
+        message: infoRes.error ?? `HTTP ${infoRes.status}`
+      });
     }
     const channel = (infoRes.data?.channels ?? []).find((candidate) => candidate.name === channelName);
     if (!channel) {
-      fail("NOT_FOUND", `Channel not found: ${opts.target}`);
+      throw new CliError({
+        code: "NOT_FOUND",
+        message: `Channel not found: ${target}`
+      });
     }
     if (channel.joined) {
-      process.stdout.write(formatAlreadyJoined(opts.target) + "\n");
+      writeText(ctx.io, formatAlreadyJoined(target) + "\n");
       return;
     }
     const joinRes = await client.request(
       "POST",
-      `/internal/agent/${encodeURIComponent(ctx.agentId)}/channels/${encodeURIComponent(channel.id)}/join`
+      `/internal/agent/${encodeURIComponent(agentContext.agentId)}/channels/${encodeURIComponent(channel.id)}/join`
     );
     if (!joinRes.ok) {
-      const code = joinRes.status >= 500 ? "SERVER_5XX" : "JOIN_FAILED";
-      fail(code, joinRes.error ?? `HTTP ${joinRes.status}`);
+      throw new CliError({
+        code: joinRes.status >= 500 ? "SERVER_5XX" : "JOIN_FAILED",
+        message: joinRes.error ?? `HTTP ${joinRes.status}`
+      });
     }
-    process.stdout.write(formatJoinChannelResult(opts.target) + "\n");
-  });
+    writeText(ctx.io, formatJoinChannelResult(target) + "\n");
+  }
+);
+function registerChannelJoinCommand(parent, runtimeOptions) {
+  registerCliCommand(parent, channelJoinCommand, runtimeOptions);
 }
 
 // src/commands/server/info.ts
-function registerServerInfoCommand(parent) {
-  parent.command("info").description("List channels, agents, and humans on the current server").action(async () => {
-    let ctx;
-    try {
-      ctx = loadAgentContext();
-    } catch (err) {
-      if (err instanceof AgentBootstrapError) fail(err.code, err.message);
-      throw err;
-    }
-    const client = new ApiClient(ctx);
+var serverInfoCommand = defineCommand(
+  {
+    name: "info",
+    description: "List channels, agents, and humans on the current server"
+  },
+  async (ctx) => {
+    const agentContext = ctx.loadAgentContext();
+    const client = ctx.createApiClient(agentContext);
     const res = await client.request(
       "GET",
-      `/internal/agent/${encodeURIComponent(ctx.agentId)}/server`
+      `/internal/agent/${encodeURIComponent(agentContext.agentId)}/server`
     );
     if (!res.ok) {
       const code = res.status >= 500 ? "SERVER_5XX" : "INFO_FAILED";
-      fail(code, res.error ?? `HTTP ${res.status}`);
+      throw new CliError({
+        code,
+        message: res.error ?? `HTTP ${res.status}`
+      });
     }
     const data = res.data;
     if (data?.runtimeContext) {
       data.runtimeContext = {
         ...data.runtimeContext,
-        workspacePath: data.runtimeContext.workspacePath ?? process.env.SLOCK_CURRENT_WORKSPACE_PATH ?? null
+        workspacePath: data.runtimeContext.workspacePath ?? ctx.env.SLOCK_CURRENT_WORKSPACE_PATH ?? null
       };
     }
-    process.stdout.write(formatServerInfo(data));
-  });
+    writeText(ctx.io, formatServerInfo(data));
+  }
+);
+function registerServerInfoCommand(parent, runtimeOptions) {
+  registerCliCommand(parent, serverInfoCommand, runtimeOptions);
+}
+
+// src/commands/knowledge/get.ts
+function buildKnowledgeGetPath(agentId, topic, opts) {
+  const params = new URLSearchParams();
+  params.set("topic", topic);
+  if (opts.reason) params.set("reason", opts.reason);
+  if (opts.turnId) params.set("turn_id", opts.turnId);
+  if (opts.traceId) params.set("trace_id", opts.traceId);
+  return `/internal/agent/${encodeURIComponent(agentId)}/knowledge?${params.toString()}`;
+}
+function formatKnowledgeStdout(content) {
+  return content.endsWith("\n") ? content : `${content}
+`;
+}
+function toKnowledgeErrorCode(errorCode2, status) {
+  switch (errorCode2) {
+    case "INVALID_JSON_RESPONSE":
+    case "SCOPE_DENIED":
+    case "knowledge_agent_missing":
+    case "knowledge_internal_error":
+    case "knowledge_not_found":
+    case "knowledge_reason_invalid":
+    case "knowledge_source_invalid":
+    case "knowledge_topic_invalid":
+    case "knowledge_trace_id_invalid":
+    case "knowledge_turn_id_invalid":
+    case "unsupported_capability":
+      return errorCode2;
+    default:
+      return status >= 500 ? "SERVER_5XX" : "KNOWLEDGE_GET_FAILED";
+  }
+}
+var knowledgeGetCommand = defineCommand(
+  {
+    name: "get",
+    description: "Fetch an agent knowledge topic from the current server",
+    arguments: ["<topic>"],
+    options: [
+      {
+        flags: "--reason <text>",
+        description: "Optional rationale for fetching this topic (>=12 chars when provided)"
+      },
+      {
+        flags: "--turn-id <id>",
+        description: "Optional turn id for correlation in the knowledge event"
+      },
+      {
+        flags: "--trace-id <id>",
+        description: "Optional trace id for correlation in the knowledge event"
+      }
+    ]
+  },
+  async (ctx, topic, opts) => {
+    const agentContext = ctx.loadAgentContext();
+    const client = ctx.createApiClient(agentContext);
+    const res = await client.request(
+      "GET",
+      buildKnowledgeGetPath(agentContext.agentId, topic, opts)
+    );
+    if (!res.ok) {
+      throw new CliError({
+        code: toKnowledgeErrorCode(res.errorCode, 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;
+    if (!data || data.ok !== true) {
+      throw new CliError({
+        code: "KNOWLEDGE_GET_FAILED",
+        message: "Server returned an unexpected response shape"
+      });
+    }
+    writeText(ctx.io, formatKnowledgeStdout(data.content));
+  }
+);
+function registerKnowledgeGetCommand(parent, runtimeOptions) {
+  registerCliCommand(parent, knowledgeGetCommand, runtimeOptions);
 }
 
 // src/commands/thread/unfollow.ts
@@ -15237,31 +15753,43 @@ function parseThreadTarget(target) {
 function formatUnfollowThreadResult(target) {
   return `Unfollowed ${target}. You can still inspect the thread when its parent conversation is visible, but you will no longer receive ordinary thread delivery unless you follow it again or are mentioned.`;
 }
-function registerThreadUnfollowCommand(parent) {
-  parent.command("unfollow").description("Stop following a thread you no longer need ordinary delivery for").requiredOption("--target <target>", "Thread target, e.g. '#engineering:abcd1234' or 'dm:@alice:abcd1234'").action(async (opts) => {
-    const thread = parseThreadTarget(opts.target);
+var threadUnfollowCommand = defineCommand(
+  {
+    name: "unfollow",
+    description: "Stop following a thread you no longer need ordinary delivery for",
+    options: [
+      {
+        flags: "--target <target>",
+        description: "Thread target, e.g. '#engineering:abcd1234' or 'dm:@alice:abcd1234'"
+      }
+    ]
+  },
+  async (ctx, opts) => {
+    const thread = parseThreadTarget(opts.target ?? "");
     if (!thread) {
-      fail("INVALID_TARGET", "Thread must be a thread target like '#channel:abcd1234', 'dm:@peer:abcd1234', or a thread channel UUID.");
-    }
-    let ctx;
-    try {
-      ctx = loadAgentContext();
-    } catch (err) {
-      if (err instanceof AgentBootstrapError) fail(err.code, err.message);
-      throw err;
+      throw new CliError({
+        code: "INVALID_TARGET",
+        message: "Thread must be a thread target like '#channel:abcd1234', 'dm:@peer:abcd1234', or a thread channel UUID."
+      });
     }
-    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)}/threads/unfollow`,
+      `/internal/agent/${encodeURIComponent(agentContext.agentId)}/threads/unfollow`,
       { thread }
     );
     if (!res.ok) {
-      const code = res.status >= 500 ? "SERVER_5XX" : "UNFOLLOW_FAILED";
-      fail(code, res.error ?? `HTTP ${res.status}`);
+      throw new CliError({
+        code: res.status >= 500 ? "SERVER_5XX" : "UNFOLLOW_FAILED",
+        message: res.error ?? `HTTP ${res.status}`
+      });
     }
-    process.stdout.write(formatUnfollowThreadResult(thread) + "\n");
-  });
+    writeText(ctx.io, formatUnfollowThreadResult(thread) + "\n");
+  }
+);
+function registerThreadUnfollowCommand(parent, runtimeOptions) {
+  registerCliCommand(parent, threadUnfollowCommand, runtimeOptions);
 }
 
 // src/commands/message/_format.ts
@@ -15434,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);
@@ -15451,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) {
@@ -15603,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.",
@@ -15661,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;
     }
@@ -15692,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 = "";
@@ -15721,24 +16261,28 @@ 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
-async function drainInbox(ctx, opts) {
-  const client = new ApiClient(ctx);
+async function drainInbox(ctx, opts, client = new ApiClient(ctx)) {
   const agentPath = `/internal/agent/${encodeURIComponent(ctx.agentId)}`;
   const failCode = opts.block ? "WAIT_FAILED" : "CHECK_FAILED";
   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) {
-    const code = res.status >= 500 ? "SERVER_5XX" : failCode;
-    fail(code, res.error ?? `HTTP ${res.status}`);
+    throw new CliError({
+      code: res.status >= 500 ? "SERVER_5XX" : failCode,
+      message: res.error ?? `HTTP ${res.status}`
+    });
   }
   const messages = res.data?.messages ?? [];
   if (ctx.clientMode === "managed-runner" || ctx.clientMode === "self-hosted-runner") {
@@ -15754,18 +16298,24 @@ async function drainInbox(ctx, opts) {
 }
 
 // src/commands/message/check.ts
-function registerCheckCommand(parent) {
-  parent.command("check").description("Drain the agent inbox (non-blocking). Acks delivered seqs before returning.").action(async () => {
-    let ctx;
-    try {
-      ctx = loadAgentContext();
-    } catch (err) {
-      if (err instanceof AgentBootstrapError) fail(err.code, err.message);
-      throw err;
-    }
-    const result = await drainInbox(ctx, { block: false });
-    process.stdout.write(formatMessages(result.messages) + "\n");
-  });
+var messageCheckCommand = defineCommand(
+  {
+    name: "check",
+    description: "Drain the agent inbox (non-blocking). Acks delivered seqs before returning."
+  },
+  async (ctx) => {
+    const agentContext = ctx.loadAgentContext();
+    const result = await drainInbox(
+      agentContext,
+      { block: false },
+      ctx.createApiClient(agentContext)
+    );
+    writeText(ctx.io, `${formatMessages(result.messages)}
+`);
+  }
+);
+function registerCheckCommand(parent, runtimeOptions) {
+  registerCliCommand(parent, messageCheckCommand, runtimeOptions);
 }
 
 // src/commands/message/read.ts
@@ -15773,39 +16323,80 @@ function parsePositiveInt(name, raw) {
   if (raw === void 0) return void 0;
   const n = Number(raw);
   if (!Number.isFinite(n) || !Number.isInteger(n) || n <= 0) {
-    fail("INVALID_ARG", `--${name} must be a positive integer; got ${raw}`);
+    throw new CliError({
+      code: "INVALID_ARG",
+      message: `--${name} must be a positive integer; got ${raw}`
+    });
   }
   return n;
 }
-function registerReadCommand(parent) {
-  parent.command("read").description("Read message history for a channel, DM, or thread").requiredOption("--channel <target>", "Target: '#channel', 'dm:@peer', '#channel:threadId', 'dm:@peer:threadId'").option("--before <seq>", "Return messages strictly before this seq (paginate backwards)").option("--after <seq>", "Return messages strictly after this seq (paginate forwards)").option("--around <idOrSeq>", "Center the window on this messageId or seq").option("--limit <n>", "Max messages to return (server default applies if omitted)").action(async (opts) => {
-    let ctx;
-    try {
-      ctx = loadAgentContext();
-    } catch (err) {
-      if (err instanceof AgentBootstrapError) fail(err.code, err.message);
-      throw err;
-    }
-    const before = parsePositiveInt("before", opts.before);
-    const after = parsePositiveInt("after", opts.after);
-    const limit = parsePositiveInt("limit", opts.limit);
-    const params = new URLSearchParams();
-    params.set("channel", opts.channel);
-    if (before !== void 0) params.set("before", String(before));
-    if (after !== void 0) params.set("after", String(after));
-    if (opts.around !== void 0) params.set("around", opts.around);
-    if (limit !== void 0) params.set("limit", String(limit));
-    const client = new ApiClient(ctx);
+function buildReadPath(agentId, opts) {
+  const params = new URLSearchParams();
+  params.set("channel", opts.channel);
+  if (opts.before !== void 0) params.set("before", String(opts.before));
+  if (opts.after !== void 0) params.set("after", String(opts.after));
+  if (opts.around !== void 0) params.set("around", opts.around);
+  if (opts.limit !== void 0) params.set("limit", String(opts.limit));
+  return `/internal/agent/${encodeURIComponent(agentId)}/history?${params.toString()}`;
+}
+function validateReadOpts(opts) {
+  const channel = opts.channel?.trim();
+  if (!channel) {
+    throw new CliError({
+      code: "INVALID_ARG",
+      message: "--channel is required"
+    });
+  }
+  const before = parsePositiveInt("before", opts.before);
+  const after = parsePositiveInt("after", opts.after);
+  const limit = parsePositiveInt("limit", opts.limit);
+  return {
+    channel,
+    ...before !== void 0 ? { before } : {},
+    ...after !== void 0 ? { after } : {},
+    ...opts.around !== void 0 ? { around: opts.around } : {},
+    ...limit !== void 0 ? { limit } : {}
+  };
+}
+var messageReadCommand = defineCommand(
+  {
+    name: "read",
+    description: "Read message history for a channel, DM, or thread",
+    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)" },
+      { flags: "--after <seq>", description: "Return messages strictly after this seq (paginate forwards)" },
+      { flags: "--around <idOrSeq>", description: "Center the window on this messageId or seq" },
+      { flags: "--limit <n>", description: "Max messages to return (server default applies if omitted)" }
+    ]
+  },
+  async (ctx, opts) => {
+    const readOpts = validateReadOpts(opts);
+    const agentContext = ctx.loadAgentContext();
+    const client = ctx.createApiClient(agentContext);
     const res = await client.request(
       "GET",
-      `/internal/agent/${encodeURIComponent(ctx.agentId)}/history?${params.toString()}`
+      buildReadPath(agentContext.agentId, readOpts)
     );
     if (!res.ok) {
-      const code = res.status >= 500 ? "SERVER_5XX" : "READ_FAILED";
-      fail(code, res.error ?? `HTTP ${res.status}`);
+      throw new CliError({
+        code: res.status >= 500 ? "SERVER_5XX" : "READ_FAILED",
+        message: res.error ?? `HTTP ${res.status}`
+      });
     }
-    process.stdout.write(formatHistory(opts.channel, res.data, { around: opts.around, after, before }) + "\n");
-  });
+    writeText(
+      ctx.io,
+      `${formatHistory(readOpts.channel, res.data, {
+        around: readOpts.around,
+        after: readOpts.after,
+        before: readOpts.before
+      })}
+`
+    );
+  }
+);
+function registerReadCommand(parent, runtimeOptions) {
+  registerCliCommand(parent, messageReadCommand, runtimeOptions);
 }
 
 // src/commands/message/search.ts
@@ -15813,56 +16404,116 @@ var UUID_RE2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
 function normalizeMemberHandleRef(raw) {
   const trimmed = raw.trim();
   if (!trimmed) {
-    fail("INVALID_ARG", "--sender must not be empty");
+    throw new CliError({
+      code: "INVALID_ARG",
+      message: "--sender must not be empty"
+    });
   }
   if (UUID_RE2.test(trimmed)) {
-    fail("INVALID_ARG", "--sender expects a member handle like @alice, not a UUID");
+    throw new CliError({
+      code: "INVALID_ARG",
+      message: "--sender expects a member handle like @alice, not a UUID"
+    });
   }
   const handle = trimmed.replace(/^@/, "").trim();
   if (!handle) {
-    fail("INVALID_ARG", "--sender handle must not be empty");
+    throw new CliError({
+      code: "INVALID_ARG",
+      message: "--sender handle must not be empty"
+    });
   }
   return handle;
 }
-function registerSearchCommand(parent) {
-  parent.command("search").description("Search messages across channels the agent can see").requiredOption("--query <q>", "Search query string").option("--channel <target>", "Restrict to a single channel/DM/thread").option("--sender <handle>", "Restrict to messages by sender handle, e.g. @alice").option("--sort <mode>", "Sort results by relevance or recent (default: relevance)").option("--before <iso>", "Only messages before this ISO datetime").option("--after <iso>", "Only messages after this ISO datetime").option("--limit <n>", "Max results (server default applies if omitted)").action(async (opts) => {
-    let ctx;
-    try {
-      ctx = loadAgentContext();
-    } catch (err) {
-      if (err instanceof AgentBootstrapError) fail(err.code, err.message);
-      throw err;
-    }
-    let limit;
-    if (opts.limit !== void 0) {
-      const n = Number(opts.limit);
-      if (!Number.isFinite(n) || !Number.isInteger(n) || n <= 0) {
-        fail("INVALID_ARG", `--limit must be a positive integer; got ${opts.limit}`);
-      }
-      limit = n;
-    }
-    if (opts.sort !== void 0 && opts.sort !== "relevance" && opts.sort !== "recent") {
-      fail("INVALID_ARG", `--sort must be "relevance" or "recent"; got ${opts.sort}`);
-    }
-    const params = new URLSearchParams();
-    params.set("q", opts.query);
-    if (opts.channel) params.set("channel", opts.channel);
-    if (opts.sender) params.set("sender", normalizeMemberHandleRef(opts.sender));
-    if (opts.sort) params.set("sort", opts.sort);
-    if (opts.before) params.set("before", opts.before);
-    if (opts.after) params.set("after", opts.after);
-    if (limit !== void 0) params.set("limit", String(limit));
-    const client = new ApiClient(ctx);
+function parsePositiveInt2(name, raw) {
+  if (raw === void 0) return void 0;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || !Number.isInteger(n) || n <= 0) {
+    throw new CliError({
+      code: "INVALID_ARG",
+      message: `--${name} must be a positive integer; got ${raw}`
+    });
+  }
+  return n;
+}
+function normalizeSearchOpts(opts) {
+  const query = opts.query?.trim();
+  if (!query) {
+    throw new CliError({
+      code: "INVALID_ARG",
+      message: "--query is required"
+    });
+  }
+  if (opts.sort !== void 0 && opts.sort !== "relevance" && opts.sort !== "recent") {
+    throw new CliError({
+      code: "INVALID_ARG",
+      message: `--sort must be "relevance" or "recent"; got ${opts.sort}`
+    });
+  }
+  const limit = parsePositiveInt2("limit", opts.limit);
+  return {
+    query,
+    ...opts.channel ? { channel: opts.channel } : {},
+    ...opts.sender ? { sender: normalizeMemberHandleRef(opts.sender) } : {},
+    ...opts.sort ? { sort: opts.sort } : {},
+    ...opts.before ? { before: opts.before } : {},
+    ...opts.after ? { after: opts.after } : {},
+    ...limit !== void 0 ? { limit } : {}
+  };
+}
+function buildSearchPath(agentId, opts) {
+  const params = new URLSearchParams();
+  params.set("q", opts.query);
+  if (opts.channel) params.set("channel", opts.channel);
+  if (opts.sender) params.set("sender", opts.sender);
+  if (opts.sort) params.set("sort", opts.sort);
+  if (opts.before) params.set("before", opts.before);
+  if (opts.after) params.set("after", opts.after);
+  if (opts.limit !== void 0) params.set("limit", String(opts.limit));
+  return `/internal/agent/${encodeURIComponent(agentId)}/search?${params.toString()}`;
+}
+function toSearchErrorCode(errorCode2, status) {
+  switch (errorCode2) {
+    case "SCOPE_DENIED":
+    case "INVALID_JSON_RESPONSE":
+      return errorCode2;
+    default:
+      return status >= 500 ? "SERVER_5XX" : "SEARCH_FAILED";
+  }
+}
+var messageSearchCommand = defineCommand(
+  {
+    name: "search",
+    description: "Search messages across channels the agent can see",
+    options: [
+      { flags: "--query <q>", description: "Search query string" },
+      { flags: "--channel <target>", description: "Restrict to a single channel/DM/thread" },
+      { flags: "--sender <handle>", description: "Restrict to messages by sender handle, e.g. @alice" },
+      { flags: "--sort <mode>", description: "Sort results by relevance or recent (default: relevance)" },
+      { flags: "--before <iso>", description: "Only messages before this ISO datetime" },
+      { flags: "--after <iso>", description: "Only messages after this ISO datetime" },
+      { flags: "--limit <n>", description: "Max results (server default applies if omitted)" }
+    ]
+  },
+  async (ctx, opts) => {
+    const searchOpts = normalizeSearchOpts(opts);
+    const agentContext = ctx.loadAgentContext();
+    const client = ctx.createApiClient(agentContext);
     const res = await client.request(
       "GET",
-      `/internal/agent/${encodeURIComponent(ctx.agentId)}/search?${params.toString()}`
+      buildSearchPath(agentContext.agentId, searchOpts)
     );
     if (!res.ok) {
-      const code = res.errorCode ?? (res.status >= 500 ? "SERVER_5XX" : "SEARCH_FAILED");
-      fail(code, res.error ?? `HTTP ${res.status}`);
+      throw new CliError({
+        code: toSearchErrorCode(res.errorCode, res.status),
+        message: res.error ?? `HTTP ${res.status}`
+      });
     }
-    process.stdout.write(formatSearchResults(opts.query, res.data) + "\n");
-  });
+    writeText(ctx.io, `${formatSearchResults(searchOpts.query, res.data)}
+`);
+  }
+);
+function registerSearchCommand(parent, runtimeOptions) {
+  registerCliCommand(parent, messageSearchCommand, runtimeOptions);
 }
 
 // src/commands/message/react.ts
@@ -15873,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
@@ -15995,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);
@@ -16062,42 +16727,70 @@ 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
 import { writeFileSync } from "fs";
-function registerAttachmentViewCommand(parent) {
-  parent.command("view").description("Download an attachment by id and save it to a local path").requiredOption("--id <attachmentId>", "Attachment UUID").requiredOption("--output <path>", "Local path to write the file to").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);
+function validateViewOpts(opts) {
+  const id = opts.id?.trim();
+  const output = opts.output;
+  if (!id) {
+    throw new CliError({
+      code: "INVALID_ARG",
+      message: "--id is required"
+    });
+  }
+  if (!output) {
+    throw new CliError({
+      code: "INVALID_ARG",
+      message: "--output is required"
+    });
+  }
+  return { id, output };
+}
+var attachmentViewCommand = defineCommand(
+  {
+    name: "view",
+    description: "Download an attachment by id and save it to a local path",
+    options: [
+      { flags: "--id <attachmentId>", description: "Attachment UUID" },
+      { flags: "--output <path>", description: "Local path to write the file to" }
+    ]
+  },
+  async (ctx, opts) => {
+    const { id, output } = validateViewOpts(opts);
+    const agentContext = ctx.loadAgentContext();
+    const client = ctx.createApiClient(agentContext);
     const res = await client.requestRaw(
       "GET",
-      `/api/attachments/${encodeURIComponent(opts.id)}`
+      `/api/attachments/${encodeURIComponent(id)}`
     );
     if (!res.ok) {
-      const code = res.status >= 500 ? "SERVER_5XX" : "VIEW_FAILED";
-      fail(code, res.error ?? `HTTP ${res.status}`);
+      throw new CliError({
+        code: res.status >= 500 ? "SERVER_5XX" : "VIEW_FAILED",
+        message: res.error ?? `HTTP ${res.status}`
+      });
     }
     const buffer = Buffer.from(await res.response.arrayBuffer());
-    writeFileSync(opts.output, buffer);
-    process.stdout.write(`Downloaded to: ${opts.output}
+    writeFileSync(output, buffer);
+    writeText(ctx.io, `Downloaded to: ${output}
 `);
-  });
+  }
+);
+function registerAttachmentViewCommand(parent, runtimeOptions) {
+  registerCliCommand(parent, attachmentViewCommand, runtimeOptions);
 }
 
 // src/commands/task/_format.ts
@@ -16155,188 +16848,288 @@ function formatTaskStatusUpdated(taskNumber, status) {
 
 // src/commands/task/list.ts
 var VALID_STATUSES = /* @__PURE__ */ new Set(["all", "todo", "in_progress", "in_review", "done", "closed"]);
-function registerTaskListCommand(parent) {
-  parent.command("list").description("List tasks in a channel").requiredOption("--channel <target>", "Channel target: '#channel'").option("--status <s>", "Filter: all|todo|in_progress|in_review|done (default: server-side)").action(async (opts) => {
-    let ctx;
-    try {
-      ctx = loadAgentContext();
-    } catch (err) {
-      if (err instanceof AgentBootstrapError) fail(err.code, err.message);
-      throw err;
-    }
-    if (opts.status && !VALID_STATUSES.has(opts.status)) {
-      fail("INVALID_ARG", `--status must be one of ${Array.from(VALID_STATUSES).join("|")}; got ${opts.status}`);
-    }
-    const params = new URLSearchParams();
-    params.set("channel", opts.channel);
-    if (opts.status) params.set("status", opts.status);
-    const client = new ApiClient(ctx);
+function buildTaskListPath(agentId, opts) {
+  const params = new URLSearchParams();
+  params.set("channel", opts.channel);
+  if (opts.status) params.set("status", opts.status);
+  return `/internal/agent/${encodeURIComponent(agentId)}/tasks?${params.toString()}`;
+}
+function validateListOpts(opts) {
+  const channel = opts.channel?.trim();
+  if (!channel) {
+    throw new CliError({
+      code: "INVALID_ARG",
+      message: "--channel is required"
+    });
+  }
+  if (opts.status && !VALID_STATUSES.has(opts.status)) {
+    throw new CliError({
+      code: "INVALID_ARG",
+      message: `--status must be one of ${Array.from(VALID_STATUSES).join("|")}; got ${opts.status}`
+    });
+  }
+  return {
+    channel,
+    ...opts.status ? { status: opts.status } : {}
+  };
+}
+var taskListCommand = defineCommand(
+  {
+    name: "list",
+    description: "List tasks in a channel",
+    options: [
+      { flags: "--channel <target>", description: "Channel target: '#channel'" },
+      { flags: "--status <s>", description: "Filter: all|todo|in_progress|in_review|done (default: server-side)" }
+    ]
+  },
+  async (ctx, opts) => {
+    const listOpts = validateListOpts(opts);
+    const agentContext = ctx.loadAgentContext();
+    const client = ctx.createApiClient(agentContext);
     const res = await client.request(
       "GET",
-      `/internal/agent/${encodeURIComponent(ctx.agentId)}/tasks?${params.toString()}`
+      buildTaskListPath(agentContext.agentId, listOpts)
     );
     if (!res.ok) {
-      const code = res.status >= 500 ? "SERVER_5XX" : "LIST_FAILED";
-      fail(code, res.error ?? `HTTP ${res.status}`);
+      throw new CliError({
+        code: res.status >= 500 ? "SERVER_5XX" : "LIST_FAILED",
+        message: res.error ?? `HTTP ${res.status}`
+      });
     }
-    process.stdout.write(formatTaskList(opts.channel, res.data, opts.status) + "\n");
-  });
+    writeText(ctx.io, `${formatTaskList(listOpts.channel, res.data, listOpts.status)}
+`);
+  }
+);
+function registerTaskListCommand(parent, runtimeOptions) {
+  registerCliCommand(parent, taskListCommand, 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
-function registerTaskUnclaimCommand(parent) {
-  parent.command("unclaim").description("Release a previously-claimed task").requiredOption("--channel <target>", "Channel target: '#channel'").requiredOption("--number <n>", "Task number to unclaim").action(async (opts) => {
-    let ctx;
-    try {
-      ctx = loadAgentContext();
-    } catch (err) {
-      if (err instanceof AgentBootstrapError) fail(err.code, err.message);
-      throw err;
-    }
-    const n = Number(opts.number);
-    if (!Number.isFinite(n) || !Number.isInteger(n) || n <= 0) {
-      fail("INVALID_ARG", `--number must be a positive integer; got ${opts.number}`);
-    }
-    const client = new ApiClient(ctx);
+function parseTaskNumber(raw) {
+  const n = Number(raw);
+  if (!Number.isFinite(n) || !Number.isInteger(n) || n <= 0) {
+    throw new CliError({
+      code: "INVALID_ARG",
+      message: `--number must be a positive integer; got ${raw}`
+    });
+  }
+  return n;
+}
+function validateUnclaimOpts(opts) {
+  const channel = opts.channel?.trim();
+  if (!channel) {
+    throw new CliError({
+      code: "INVALID_ARG",
+      message: "--channel is required"
+    });
+  }
+  return { channel, taskNumber: parseTaskNumber(opts.number) };
+}
+var taskUnclaimCommand = defineCommand(
+  {
+    name: "unclaim",
+    description: "Release a previously-claimed task",
+    options: [
+      { flags: "--channel <target>", description: "Channel target: '#channel'" },
+      { flags: "--number <n>", description: "Task number to unclaim" }
+    ]
+  },
+  async (ctx, opts) => {
+    const { channel, taskNumber } = validateUnclaimOpts(opts);
+    const agentContext = ctx.loadAgentContext();
+    const client = ctx.createApiClient(agentContext);
     const res = await client.request(
       "POST",
-      `/internal/agent/${encodeURIComponent(ctx.agentId)}/tasks/unclaim`,
-      { channel: opts.channel, task_number: n }
+      `/internal/agent/${encodeURIComponent(agentContext.agentId)}/tasks/unclaim`,
+      { channel, task_number: taskNumber }
     );
     if (!res.ok) {
-      const code = res.status >= 500 ? "SERVER_5XX" : "UNCLAIM_FAILED";
-      fail(code, res.error ?? `HTTP ${res.status}`);
+      throw new CliError({
+        code: res.status >= 500 ? "SERVER_5XX" : "UNCLAIM_FAILED",
+        message: res.error ?? `HTTP ${res.status}`
+      });
     }
-    process.stdout.write(formatTaskUnclaimed(n) + "\n");
-  });
+    writeText(ctx.io, `${formatTaskUnclaimed(taskNumber)}
+`);
+  }
+);
+function registerTaskUnclaimCommand(parent, runtimeOptions) {
+  registerCliCommand(parent, taskUnclaimCommand, runtimeOptions);
 }
 
 // src/commands/task/update.ts
 var STATUSES = ["todo", "in_progress", "in_review", "done", "closed"];
-function registerTaskUpdateCommand(parent) {
-  parent.command("update").description("Update task status").requiredOption("--channel <target>", "Channel target: '#channel'").requiredOption("--number <n>", "Task number to update").requiredOption(
-    "--status <status>",
-    `New status. One of: ${STATUSES.join(", ")}`
-  ).action(async (opts) => {
-    let ctx;
-    try {
-      ctx = loadAgentContext();
-    } catch (err) {
-      if (err instanceof AgentBootstrapError) fail(err.code, err.message);
-      throw err;
-    }
-    const n = Number(opts.number);
-    if (!Number.isFinite(n) || !Number.isInteger(n) || n <= 0) {
-      fail("INVALID_ARG", `--number must be a positive integer; got ${opts.number}`);
-    }
-    if (!STATUSES.includes(opts.status)) {
-      fail(
-        "INVALID_ARG",
-        `--status must be one of: ${STATUSES.join(", ")}; got ${opts.status}`
-      );
-    }
-    const client = new ApiClient(ctx);
+function parseTaskNumber2(raw) {
+  const n = Number(raw);
+  if (!Number.isFinite(n) || !Number.isInteger(n) || n <= 0) {
+    throw new CliError({
+      code: "INVALID_ARG",
+      message: `--number must be a positive integer; got ${raw}`
+    });
+  }
+  return n;
+}
+function parseStatus(raw) {
+  if (!raw || !STATUSES.includes(raw)) {
+    throw new CliError({
+      code: "INVALID_ARG",
+      message: `--status must be one of: ${STATUSES.join(", ")}; got ${raw}`
+    });
+  }
+  return raw;
+}
+function validateUpdateOpts(opts) {
+  const channel = opts.channel?.trim();
+  if (!channel) {
+    throw new CliError({
+      code: "INVALID_ARG",
+      message: "--channel is required"
+    });
+  }
+  return {
+    channel,
+    taskNumber: parseTaskNumber2(opts.number),
+    status: parseStatus(opts.status)
+  };
+}
+var taskUpdateCommand = defineCommand(
+  {
+    name: "update",
+    description: "Update task status",
+    options: [
+      { flags: "--channel <target>", description: "Channel target: '#channel'" },
+      { flags: "--number <n>", description: "Task number to update" },
+      { flags: "--status <status>", description: `New status. One of: ${STATUSES.join(", ")}` }
+    ]
+  },
+  async (ctx, opts) => {
+    const { channel, taskNumber, status } = validateUpdateOpts(opts);
+    const agentContext = ctx.loadAgentContext();
+    const client = ctx.createApiClient(agentContext);
     const res = await client.request(
       "POST",
-      `/internal/agent/${encodeURIComponent(ctx.agentId)}/tasks/update-status`,
-      { channel: opts.channel, task_number: n, status: opts.status }
+      `/internal/agent/${encodeURIComponent(agentContext.agentId)}/tasks/update-status`,
+      { channel, task_number: taskNumber, status }
     );
     if (!res.ok) {
-      const code = res.status >= 500 ? "SERVER_5XX" : "UPDATE_FAILED";
-      fail(code, res.error ?? `HTTP ${res.status}`);
+      throw new CliError({
+        code: res.status >= 500 ? "SERVER_5XX" : "UPDATE_FAILED",
+        message: res.error ?? `HTTP ${res.status}`
+      });
     }
     if (isFreshnessHeldResponse(res.data)) {
-      process.stdout.write(formatFreshnessHoldOutput(opts.channel, res.data, {
+      writeText(ctx.io, formatFreshnessHoldOutput(channel, res.data, {
         heldAction: "Your task status update was not applied.",
         draftInstructions: "After reviewing the newer context, rerun the task update command if it is still correct.\n"
       }));
       return;
     }
-    process.stdout.write(formatTaskStatusUpdated(n, opts.status) + "\n");
-  });
+    writeText(ctx.io, `${formatTaskStatusUpdated(taskNumber, status)}
+`);
+  }
+);
+function registerTaskUpdateCommand(parent, runtimeOptions) {
+  registerCliCommand(parent, taskUpdateCommand, runtimeOptions);
 }
 
 // src/commands/profile/_format.ts
@@ -16403,39 +17196,57 @@ function normalizeTarget(target) {
   if (target === void 0) return null;
   const trimmed = target.trim();
   if (!trimmed) {
-    fail("INVALID_ARG", "profile target must not be empty");
+    throw new CliError({
+      code: "INVALID_ARG",
+      message: "profile target must not be empty"
+    });
   }
   if (!trimmed.startsWith("@")) {
-    fail("INVALID_ARG", "profile target must start with @");
+    throw new CliError({
+      code: "INVALID_ARG",
+      message: "profile target must start with @"
+    });
   }
   return trimmed;
 }
-function registerProfileShowCommand(parent) {
-  parent.command("show").description("Show a profile. Omit the target to show your own profile.").argument("[target]", "Handle like @alice; omit to show your own profile").option("--json", "Emit machine-readable JSON").action(async (target, opts) => {
-    let ctx;
-    try {
-      ctx = loadAgentContext();
-    } catch (err) {
-      if (err instanceof AgentBootstrapError) fail(err.code, err.message);
-      throw err;
-    }
+function buildProfileShowPath(agentId, target) {
+  const base = `/internal/agent/${encodeURIComponent(agentId)}/profile`;
+  if (!target) return base;
+  const params = new URLSearchParams();
+  params.set("target", target);
+  return `${base}?${params.toString()}`;
+}
+var profileShowCommand = defineCommand(
+  {
+    name: "show",
+    description: "Show a profile. Omit the target to show your own profile.",
+    arguments: ["[target]"],
+    options: [{ flags: "--json", description: "Emit machine-readable JSON" }]
+  },
+  async (ctx, target, opts = {}) => {
+    const agentContext = ctx.loadAgentContext();
+    const client = ctx.createApiClient(agentContext);
     const normalizedTarget = normalizeTarget(target);
-    const params = new URLSearchParams();
-    if (normalizedTarget) params.set("target", normalizedTarget);
-    const client = new ApiClient(ctx);
-    const pathname = params.size > 0 ? `/internal/agent/${encodeURIComponent(ctx.agentId)}/profile?${params.toString()}` : `/internal/agent/${encodeURIComponent(ctx.agentId)}/profile`;
-    const res = await client.request("GET", pathname);
+    const res = await client.request(
+      "GET",
+      buildProfileShowPath(agentContext.agentId, normalizedTarget)
+    );
     if (!res.ok || !res.data) {
-      const code = res.status >= 500 ? "SERVER_5XX" : "PROFILE_SHOW_FAILED";
-      fail(code, res.error ?? `HTTP ${res.status}`);
+      throw new CliError({
+        code: res.status >= 500 ? "SERVER_5XX" : "PROFILE_SHOW_FAILED",
+        message: 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(`${formatProfile(res.data)}
+    writeText(ctx.io, `${formatProfile(res.data)}
 `);
-  });
+  }
+);
+function registerProfileShowCommand(parent, runtimeOptions) {
+  registerCliCommand(parent, profileShowCommand, runtimeOptions);
 }
 
 // src/commands/profile/update.ts
@@ -16477,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`
     );
@@ -16493,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"
     );
@@ -16503,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) {
@@ -16537,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 = {};
@@ -16566,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
@@ -16631,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)}`);
@@ -16647,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}`);
     }
   }
@@ -16659,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}`);
@@ -16674,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
@@ -16708,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
@@ -16849,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();
@@ -16917,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) {
@@ -16948,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
@@ -17005,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;
     }
@@ -17064,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
@@ -17136,6 +18341,8 @@ var threadCmd = program.command("thread").description("Thread attention operatio
 registerThreadUnfollowCommand(threadCmd);
 var serverCmd = program.command("server").description("Server / workspace introspection");
 registerServerInfoCommand(serverCmd);
+var knowledgeCmd = program.command("knowledge").description("Agent knowledge retrieval (canonical Slock product knowledge topics)");
+registerKnowledgeGetCommand(knowledgeCmd);
 var messageCmd = program.command("message").description("Message operations");
 registerSendCommand(messageCmd);
 registerCheckCommand(messageCmd);
@@ -17157,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);