clisbot 0.1.17 → 0.1.20

package/dist/main.js

@@ -54471,14 +54471,22 @@ function renderPairingSetupHelpLines(prefix = "", options = {}) {
     return lines;
   }
   lines.push(`${prefix}Pairing notes:`);
+  if (shouldRenderSlack && shouldRenderTelegram) {
+    lines.push(`${prefix}  - Send a direct message (DM) to the Telegram or Slack bot. Send \`/start\` or \`hi\` to receive a pairing code.`);
+  }
   if (shouldRenderTelegram) {
-    lines.push(`${prefix}  - Telegram DMs use \`pairing\`. Send \`/start\` or \`hi\` to the Telegram bot to get a pairing code.`);
+    if (!shouldRenderSlack) {
+      lines.push(`${prefix}  - Send a direct message (DM) to the Telegram bot. Send \`/start\` or \`hi\` to receive a pairing code.`);
+    }
     lines.push(`${prefix}  - Approve the returned Telegram code with: \`clisbot pairing approve telegram <code>\``);
   }
   if (shouldRenderSlack) {
-    lines.push(`${prefix}  - Slack DMs use \`pairing\`. Say \`hi\` to the Slack bot to get a pairing code.`);
+    if (!shouldRenderTelegram) {
+      lines.push(`${prefix}  - Send a direct message (DM) to the Slack bot. Say \`hi\` to receive a pairing code.`);
+    }
     lines.push(`${prefix}  - Approve the returned Slack code with: \`clisbot pairing approve slack <code>\``);
   }
+  lines.push(`${prefix}  - Configured app owner/admin principals bypass pairing in DMs.`);
   return lines;
 }
 function renderTmuxDebugHelpLines(prefix = "") {
@@ -54585,6 +54593,12 @@ function parseCliArgs(argv) {
       args: args.slice(1)
     };
   }
+  if (command === "auth") {
+    return {
+      name: "auth",
+      args: args.slice(1)
+    };
+  }
   if (command === "pairing") {
     return {
       name: "pairing",
@@ -54607,6 +54621,10 @@ function renderCliHelp() {
   return [
     `clisbot v${getClisbotVersion()}`,
     "",
+    "Platform support:",
+    "  Linux/macOS  Supported.",
+    "  Windows      Native Windows is not supported yet. Use WSL2.",
+    "",
     "Fastest start:",
     "  1. Choose the channels you want to bootstrap explicitly.",
     "  2. Run one of these commands:",
@@ -54639,6 +54657,7 @@ function renderCliHelp() {
     "  clisbot loops <subcommand>",
     "  clisbot message <subcommand>",
     "  clisbot agents <subcommand>",
+    "  clisbot auth <subcommand>",
     "  clisbot pairing <subcommand>",
     "  clisbot init [--cli <codex|claude|gemini>] [--bot-type <personal|team>] [--persist]",
     "              [--slack-account <id> --slack-app-token <ENV_NAME|${ENV_NAME}|literal> --slack-bot-token <ENV_NAME|${ENV_NAME}|literal>]...",
@@ -54675,6 +54694,7 @@ function renderCliHelp() {
     "                     cancel --all",
     "  message            Run provider message actions such as send, react, read, edit, delete, and pins.",
     "  agents             Manage configured agents and top-level bindings.",
+    "  auth               Manage app and agent auth roles, principals, and permissions in config. See `clisbot auth --help`.",
     "  pairing            Run the pairing control CLI.",
     `  init               Seed ${configPath} and optionally create the first agent without starting clisbot.`,
     "  --version, -v      Show the installed clisbot version.",
@@ -59856,6 +59876,10 @@ var authRoleSchema = exports_external.object({
   allow: exports_external.array(exports_external.string().min(1)).default([]),
   users: exports_external.array(exports_external.string().min(1)).default([])
 });
+var authRoleOverrideSchema = exports_external.object({
+  allow: exports_external.array(exports_external.string().min(1)).optional(),
+  users: exports_external.array(exports_external.string().min(1)).optional()
+});
 var appAuthSchema = exports_external.object({
   ownerClaimWindowMinutes: exports_external.number().int().positive().default(30),
   defaultRole: exports_external.string().min(1).default("member"),
@@ -59887,11 +59911,15 @@ var agentAuthSchema = exports_external.object({
     }
   })
 });
+var agentAuthOverrideSchema = exports_external.object({
+  defaultRole: exports_external.string().min(1).optional(),
+  roles: exports_external.record(exports_external.string(), authRoleOverrideSchema).default({})
+});
 var agentOverrideSchema = exports_external.object({
   workspace: exports_external.string().optional(),
   responseMode: exports_external.enum(["capture-pane", "message-tool"]).optional(),
   additionalMessageMode: exports_external.enum(["queue", "steer"]).optional(),
-  auth: agentAuthSchema.optional(),
+  auth: agentAuthOverrideSchema.optional(),
   runner: runnerOverrideSchema.optional(),
   stream: streamSchema.partial().optional(),
   session: sessionSchema.partial().optional()
@@ -59986,9 +60014,18 @@ var channelAgentPromptSchema = exports_external.object({
 var channelResponseModeSchema = exports_external.enum(["capture-pane", "message-tool"]);
 var channelAdditionalMessageModeSchema = exports_external.enum(["queue", "steer"]);
 var channelVerboseSchema = exports_external.enum(["off", "minimal"]);
+var surfaceNotificationModeSchema = exports_external.enum(["none", "brief", "full"]);
 var timezoneSchema = exports_external.string().refine(isValidLoopTimezone, {
   message: "Expected a valid IANA timezone such as Asia/Ho_Chi_Minh"
 });
+var surfaceNotificationsSchema = exports_external.object({
+  queueStart: surfaceNotificationModeSchema.default("brief"),
+  loopStart: surfaceNotificationModeSchema.default("brief")
+});
+var surfaceNotificationsOverrideSchema = exports_external.object({
+  queueStart: surfaceNotificationModeSchema.optional(),
+  loopStart: surfaceNotificationModeSchema.optional()
+});
 var slackRouteSchema = exports_external.object({
   requireMention: exports_external.boolean().default(true),
   allowBots: exports_external.boolean().default(false),
@@ -59999,6 +60036,7 @@ var slackRouteSchema = exports_external.object({
   response: slackResponseSchema.optional(),
   responseMode: channelResponseModeSchema.optional(),
   additionalMessageMode: channelAdditionalMessageModeSchema.optional(),
+  surfaceNotifications: surfaceNotificationsOverrideSchema.optional(),
   verbose: channelVerboseSchema.optional(),
   followUp: slackFollowUpOverrideSchema.optional(),
   timezone: timezoneSchema.optional()
@@ -60013,6 +60051,7 @@ var telegramTopicRouteSchema = exports_external.object({
   response: slackResponseSchema.optional(),
   responseMode: channelResponseModeSchema.optional(),
   additionalMessageMode: channelAdditionalMessageModeSchema.optional(),
+  surfaceNotifications: surfaceNotificationsOverrideSchema.optional(),
   verbose: channelVerboseSchema.optional(),
   followUp: slackFollowUpOverrideSchema.optional(),
   timezone: timezoneSchema.optional()
@@ -60027,6 +60066,7 @@ var telegramGroupRouteSchema = exports_external.object({
   response: slackResponseSchema.optional(),
   responseMode: channelResponseModeSchema.optional(),
   additionalMessageMode: channelAdditionalMessageModeSchema.optional(),
+  surfaceNotifications: surfaceNotificationsOverrideSchema.optional(),
   verbose: channelVerboseSchema.optional(),
   followUp: slackFollowUpOverrideSchema.optional(),
   timezone: timezoneSchema.optional(),
@@ -60045,6 +60085,7 @@ var telegramDirectMessagesSchema = exports_external.object({
   response: slackResponseSchema.optional(),
   responseMode: channelResponseModeSchema.optional(),
   additionalMessageMode: channelAdditionalMessageModeSchema.optional(),
+  surfaceNotifications: surfaceNotificationsOverrideSchema.optional(),
   verbose: channelVerboseSchema.optional(),
   followUp: slackFollowUpOverrideSchema.optional(),
   timezone: timezoneSchema.optional()
@@ -60082,6 +60123,7 @@ var telegramSchema = exports_external.object({
   response: slackResponseSchema.default("final"),
   responseMode: channelResponseModeSchema.default("message-tool"),
   additionalMessageMode: channelAdditionalMessageModeSchema.default("steer"),
+  surfaceNotifications: surfaceNotificationsSchema.optional(),
   verbose: channelVerboseSchema.default("minimal"),
   followUp: slackFollowUpSchema.default({
     mode: "auto",
@@ -60113,6 +60155,7 @@ var directMessagesSchema = exports_external.object({
   response: slackResponseSchema.optional(),
   responseMode: channelResponseModeSchema.optional(),
   additionalMessageMode: channelAdditionalMessageModeSchema.optional(),
+  surfaceNotifications: surfaceNotificationsOverrideSchema.optional(),
   verbose: channelVerboseSchema.optional(),
   followUp: slackFollowUpOverrideSchema.optional(),
   timezone: timezoneSchema.optional()
@@ -60157,6 +60200,7 @@ var slackSchema = exports_external.object({
   response: slackResponseSchema.default("final"),
   responseMode: channelResponseModeSchema.default("message-tool"),
   additionalMessageMode: channelAdditionalMessageModeSchema.default("steer"),
+  surfaceNotifications: surfaceNotificationsSchema.optional(),
   verbose: channelVerboseSchema.default("minimal"),
   followUp: slackFollowUpSchema.default({
     mode: "auto",
@@ -60308,6 +60352,10 @@ var clisbotConfigSchema = exports_external.object({
       response: "final",
       responseMode: "message-tool",
       additionalMessageMode: "steer",
+      surfaceNotifications: {
+        queueStart: "brief",
+        loopStart: "brief"
+      },
       verbose: "minimal",
       followUp: {
         mode: "auto",
@@ -60625,6 +60673,10 @@ function renderDefaultConfigTemplate(options = {}) {
         response: "final",
         responseMode: "message-tool",
         additionalMessageMode: "steer",
+        surfaceNotifications: {
+          queueStart: "brief",
+          loopStart: "brief"
+        },
         verbose: "minimal",
         followUp: {
           mode: "auto",
@@ -60666,6 +60718,10 @@ function renderDefaultConfigTemplate(options = {}) {
         response: "final",
         responseMode: "message-tool",
         additionalMessageMode: "steer",
+        surfaceNotifications: {
+          queueStart: "brief",
+          loopStart: "brief"
+        },
         verbose: "minimal",
         followUp: {
           mode: "auto",
@@ -61834,6 +61890,8 @@ function getExecutableNames(command) {
 // src/runners/tmux/client.ts
 var MAIN_WINDOW_NAME = "main";
 var TMUX_NOT_FOUND_CODE = "ENOENT";
+var TMUX_SERVER_BOOTSTRAP_TIMEOUT_MS = 1000;
+var TMUX_SERVER_BOOTSTRAP_POLL_MS = 25;
 var TMUX_SERVER_DEFAULTS = [
   ["exit-empty", "off"],
   ["destroy-unattached", "off"]
@@ -61844,6 +61902,9 @@ class TmuxClient {
   constructor(socketPath) {
     this.socketPath = socketPath;
   }
+  isServerUnavailableOutput(output) {
+    return /no server running|No such file or directory|failed to connect to server|error connecting to/i.test(output);
+  }
   async exec(args, options = {}) {
     if (!commandExists("tmux")) {
       throw new Error("tmux is not installed or not available on PATH. Install tmux and restart clisbot.");
@@ -61895,7 +61956,10 @@ class TmuxClient {
     }
     const output = `${result.stderr}
 ${result.stdout}`.trim();
-    return !output.includes("no server running");
+    if (this.isServerUnavailableOutput(output)) {
+      return false;
+    }
+    return false;
   }
   async ensureServerDefaults() {
     if (!await this.isServerRunning()) {
@@ -61905,6 +61969,35 @@ ${result.stdout}`.trim();
       await this.execOrThrow(["set-option", "-g", name, value]);
     }
   }
+  isBootstrapRetryableError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return this.isServerUnavailableOutput(message);
+  }
+  async withServerBootstrapRetry(task) {
+    const deadline = Date.now() + TMUX_SERVER_BOOTSTRAP_TIMEOUT_MS;
+    while (true) {
+      try {
+        return await task();
+      } catch (error) {
+        if (!this.isBootstrapRetryableError(error) || Date.now() >= deadline) {
+          throw error;
+        }
+        await sleep(TMUX_SERVER_BOOTSTRAP_POLL_MS);
+      }
+    }
+  }
+  async waitForSessionBootstrap(sessionName) {
+    const deadline = Date.now() + TMUX_SERVER_BOOTSTRAP_TIMEOUT_MS;
+    while (true) {
+      if (await this.hasSession(sessionName)) {
+        return;
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(`tmux session "${sessionName}" did not become reachable on socket ${this.socketPath} within ${TMUX_SERVER_BOOTSTRAP_TIMEOUT_MS}ms.`);
+      }
+      await sleep(TMUX_SERVER_BOOTSTRAP_POLL_MS);
+    }
+  }
   async newSession(params) {
     await this.execOrThrow([
       "new-session",
@@ -61917,8 +62010,13 @@ ${result.stdout}`.trim();
       params.cwd,
       params.command
     ]);
-    await this.ensureServerDefaults();
-    await this.freezeWindowName(`${params.sessionName}:${MAIN_WINDOW_NAME}`);
+    await this.waitForSessionBootstrap(params.sessionName);
+    await this.withServerBootstrapRetry(async () => {
+      await this.ensureServerDefaults();
+    });
+    await this.withServerBootstrapRetry(async () => {
+      await this.freezeWindowName(`${params.sessionName}:${MAIN_WINDOW_NAME}`);
+    });
   }
   async newWindow(params) {
     const paneId = await this.execOrThrow([
@@ -62705,40 +62803,329 @@ async function runAccountsCli(args, deps = {}) {
   throw new Error(renderAccountsHelp());
 }
 
-// src/channels/telegram/route-guidance.ts
-function renderTelegramRouteChoiceMessage(params) {
-  const chatId = String(params.chatId);
-  const topicId = params.topicId != null ? String(params.topicId) : undefined;
-  const lines = [
-    topicId != null ? "clisbot: this Telegram topic is not configured yet." : "clisbot: this Telegram group is not configured yet.",
+// src/control/auth-cli.ts
+function getEditableConfigPath3() {
+  return process.env.CLISBOT_CONFIG_PATH;
+}
+function parseRepeatedOption2(args, name) {
+  const values = [];
+  for (let index = 0;index < args.length; index += 1) {
+    if (args[index] !== name) {
+      continue;
+    }
+    const value = args[index + 1]?.trim();
+    if (!value) {
+      throw new Error(`Missing value for ${name}`);
+    }
+    values.push(value);
+  }
+  return values;
+}
+function parseSingleOption2(args, name) {
+  const values = parseRepeatedOption2(args, name);
+  if (values.length === 0) {
+    return;
+  }
+  return values[values.length - 1];
+}
+function hasFlag3(args, name) {
+  return args.includes(name);
+}
+function parseScope(raw, args) {
+  if (raw === "app") {
+    return { kind: "app" };
+  }
+  if (raw === "agent-defaults") {
+    return { kind: "agent-defaults" };
+  }
+  if (raw === "agent") {
+    const agentId = parseSingleOption2(args, "--agent");
+    if (!agentId) {
+      throw new Error("Missing value for --agent");
+    }
+    return { kind: "agent", agentId };
+  }
+  throw new Error("Scope required: app | agent-defaults | agent");
+}
+function renderAuthCliHelp() {
+  return [
+    "clisbot auth",
     "",
-    "Ask the bot owner to choose one of these:",
+    "Manage auth roles, principals, and permissions in config.",
     "",
-    "Add the whole group with the default agent:",
-    `\`clisbot channels add telegram-group ${chatId}\``,
+    "Usage:",
+    "  clisbot auth list [--json]",
+    "  clisbot auth show <app|agent-defaults|agent> [--agent <id>] [--json]",
+    "  clisbot auth add-user <app|agent-defaults|agent> --role <role> --user <principal> [--agent <id>]",
+    "  clisbot auth remove-user <app|agent-defaults|agent> --role <role> --user <principal> [--agent <id>]",
+    "  clisbot auth add-permission <app|agent-defaults|agent> --role <role> --permission <permission> [--agent <id>]",
+    "  clisbot auth remove-permission <app|agent-defaults|agent> --role <role> --permission <permission> [--agent <id>]",
     "",
-    "Add the whole group with a specific agent:",
-    `\`clisbot channels add telegram-group ${chatId} --agent <id>\``
-  ];
-  if (topicId != null) {
-    lines.push("", "Add only this topic with a specific agent:", `\`clisbot channels add telegram-group ${chatId} --topic ${topicId} --agent <id>\``);
+    "Scopes:",
+    "  app             edit app.auth",
+    "  agent-defaults  edit agents.defaults.auth",
+    "  agent           edit one agents.list[].auth override; requires --agent <id>",
+    "",
+    "Permission sets:",
+    `  app             ${APP_ADMIN_PERMISSIONS.join(", ")}`,
+    `  agent           ${DEFAULT_AGENT_ADMIN_PERMISSIONS.join(", ")}`,
+    "",
+    "Notes:",
+    "  add-user/remove-user mutate roles.<role>.users",
+    "  add-permission/remove-permission mutate roles.<role>.allow",
+    "  agent role edits clone the inherited agent-defaults role into the target agent override on first write",
+    "",
+    "Examples:",
+    "  clisbot auth add-user app --role owner --user telegram:1276408333",
+    "  clisbot auth remove-user app --role admin --user slack:U123",
+    "  clisbot auth add-user agent --agent default --role admin --user slack:U123",
+    "  clisbot auth add-permission agent-defaults --role member --permission shellExecute",
+    "  clisbot auth remove-permission agent --agent default --role member --permission shellExecute",
+    "  clisbot auth show agent-defaults",
+    "  clisbot auth list --json"
+  ].join(`
+`);
+}
+function cloneRoleDefinition(value) {
+  return {
+    allow: [...value?.allow ?? []],
+    users: [...value?.users ?? []]
+  };
+}
+function mergeRoleDefinitions(inherited, override) {
+  return {
+    allow: [...override?.allow ?? inherited?.allow ?? []],
+    users: [...override?.users ?? inherited?.users ?? []]
+  };
+}
+function mergeRoleRecord(defaults, overrides) {
+  const merged = {};
+  const roleNames = new Set([
+    ...Object.keys(defaults ?? {}),
+    ...Object.keys(overrides ?? {})
+  ]);
+  for (const roleName of roleNames) {
+    merged[roleName] = mergeRoleDefinitions(defaults?.[roleName], overrides?.[roleName]);
   }
-  if (params.includeConfigPath) {
-    lines.push("", topicId != null ? `Config path: \`channels.telegram.groups."${chatId}".topics."${topicId}"\`` : `Config path: \`channels.telegram.groups."${chatId}"\``);
-  } else {
-    lines.push("", "After that, routed commands such as `/status`, `/stop`, `/nudge`, `/followup`, and `/bash` will work here.");
+  return merged;
+}
+function normalizeUnique(values) {
+  return [...new Set(values.map((value) => value.trim()).filter(Boolean))].sort();
+}
+function ensureAgentEntry(config, agentId) {
+  const entry = config.agents.list.find((item) => item.id === agentId);
+  if (!entry) {
+    throw new Error(`Unknown agent: ${agentId}`);
   }
-  return lines.join(`
-`);
+  return entry;
+}
+function getAuthLabel(scope) {
+  if (scope.kind === "app") {
+    return "app.auth";
+  }
+  if (scope.kind === "agent-defaults") {
+    return "agents.defaults.auth";
+  }
+  return `agents.list[${scope.agentId}].auth`;
+}
+function ensureEditableRoleDefinition(role) {
+  role.allow = role.allow ?? [];
+  role.users = role.users ?? [];
+  return role;
+}
+function resolveAppRole(config, roleName) {
+  const role = config.app.auth.roles[roleName];
+  if (!role) {
+    throw new Error(`Unknown app role: ${roleName}`);
+  }
+  return ensureEditableRoleDefinition(role);
+}
+function resolveAgentDefaultsRole(config, roleName) {
+  const role = config.agents.defaults.auth.roles[roleName];
+  if (!role) {
+    throw new Error(`Unknown agent-defaults role: ${roleName}`);
+  }
+  return ensureEditableRoleDefinition(role);
+}
+function ensureAgentOverrideAuth(entry, config) {
+  if (!entry.auth) {
+    entry.auth = {
+      defaultRole: config.agents.defaults.auth.defaultRole,
+      roles: {}
+    };
+  }
+  return entry.auth;
+}
+function resolveAgentRoleForEdit(config, agentId, roleName) {
+  const entry = ensureAgentEntry(config, agentId);
+  const explicitRole = entry.auth?.roles?.[roleName];
+  if (explicitRole) {
+    return ensureEditableRoleDefinition(explicitRole);
+  }
+  const inheritedRole = config.agents.defaults.auth.roles[roleName];
+  if (!inheritedRole) {
+    throw new Error(`Unknown agent role: ${roleName}`);
+  }
+  const auth = ensureAgentOverrideAuth(entry, config);
+  auth.roles[roleName] = cloneRoleDefinition(inheritedRole);
+  return ensureEditableRoleDefinition(auth.roles[roleName]);
+}
+function resolveRoleForEdit(config, scope, roleName) {
+  if (scope.kind === "app") {
+    return resolveAppRole(config, roleName);
+  }
+  if (scope.kind === "agent-defaults") {
+    return resolveAgentDefaultsRole(config, roleName);
+  }
+  return resolveAgentRoleForEdit(config, scope.agentId, roleName);
+}
+function validatePermission(scope, permission) {
+  const trimmed = permission.trim();
+  if (!trimmed) {
+    throw new Error("Missing value for --permission");
+  }
+  const allowedPermissions = new Set(scope.kind === "app" ? APP_ADMIN_PERMISSIONS : DEFAULT_AGENT_ADMIN_PERMISSIONS);
+  if (!allowedPermissions.has(trimmed)) {
+    const sorted = [...allowedPermissions].sort().join(", ");
+    throw new Error(`Unknown permission for ${scope.kind}: ${trimmed}. Allowed: ${sorted}`);
+  }
+  return trimmed;
+}
+function buildShowPayload(config, scope) {
+  if (scope.kind === "app") {
+    return config.app.auth;
+  }
+  if (scope.kind === "agent-defaults") {
+    return config.agents.defaults.auth;
+  }
+  const entry = ensureAgentEntry(config, scope.agentId);
+  return {
+    defaultRole: entry.auth?.defaultRole ?? config.agents.defaults.auth.defaultRole,
+    roles: mergeRoleRecord(config.agents.defaults.auth.roles, entry.auth?.roles)
+  };
+}
+async function listAuth(args) {
+  const { config } = await readEditableConfig(getEditableConfigPath3());
+  const payload = {
+    app: config.app.auth,
+    agentDefaults: config.agents.defaults.auth,
+    agents: config.agents.list.map((entry) => ({
+      agentId: entry.id,
+      auth: buildShowPayload(config, { kind: "agent", agentId: entry.id })
+    }))
+  };
+  if (hasFlag3(args, "--json")) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  console.log(JSON.stringify(payload, null, 2));
+}
+async function showAuth(args) {
+  const scope = parseScope(args[0], args.slice(1));
+  const { config } = await readEditableConfig(getEditableConfigPath3());
+  const payload = buildShowPayload(config, scope);
+  if (hasFlag3(args, "--json")) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  console.log(JSON.stringify(payload, null, 2));
+}
+async function mutateUsers(mode, args) {
+  const scope = parseScope(args[0], args.slice(1));
+  const roleName = parseSingleOption2(args, "--role");
+  const principal = parseSingleOption2(args, "--user")?.trim();
+  if (!roleName) {
+    throw new Error("Missing value for --role");
+  }
+  if (!principal) {
+    throw new Error("Missing value for --user");
+  }
+  const { config, configPath } = await readEditableConfig(getEditableConfigPath3());
+  const role = resolveRoleForEdit(config, scope, roleName);
+  role.users = normalizeUnique(mode === "add" ? [...role.users, principal] : role.users.filter((value) => value !== principal));
+  await writeEditableConfig(configPath, config);
+  console.log(`${mode === "add" ? "Added" : "Removed"} user ${principal} ${mode === "add" ? "to" : "from"} ${getAuthLabel(scope)} role ${roleName}.`);
+}
+async function mutatePermissions(mode, args) {
+  const scope = parseScope(args[0], args.slice(1));
+  const roleName = parseSingleOption2(args, "--role");
+  const permission = validatePermission(scope, parseSingleOption2(args, "--permission") ?? "");
+  if (!roleName) {
+    throw new Error("Missing value for --role");
+  }
+  const { config, configPath } = await readEditableConfig(getEditableConfigPath3());
+  const role = resolveRoleForEdit(config, scope, roleName);
+  role.allow = normalizeUnique(mode === "add" ? [...role.allow, permission] : role.allow.filter((value) => value !== permission));
+  await writeEditableConfig(configPath, config);
+  console.log(`${mode === "add" ? "Added" : "Removed"} permission ${permission} ${mode === "add" ? "to" : "from"} ${getAuthLabel(scope)} role ${roleName}.`);
+}
+async function runAuthCli(args) {
+  const [command, ...rest] = args;
+  if (!command || command === "--help" || command === "-h" || command === "help") {
+    console.log(renderAuthCliHelp());
+    return;
+  }
+  if (command === "list") {
+    await listAuth(rest);
+    return;
+  }
+  if (command === "show") {
+    await showAuth(rest);
+    return;
+  }
+  if (command === "add-user") {
+    await mutateUsers("add", rest);
+    return;
+  }
+  if (command === "remove-user") {
+    await mutateUsers("remove", rest);
+    return;
+  }
+  if (command === "add-permission") {
+    await mutatePermissions("add", rest);
+    return;
+  }
+  if (command === "remove-permission") {
+    await mutatePermissions("remove", rest);
+    return;
+  }
+  throw new Error(renderAuthCliHelp());
 }
 
 // src/channels/mode-config-shared.ts
+function createTelegramGroupRoute() {
+  return {
+    requireMention: true,
+    allowBots: false,
+    topics: {}
+  };
+}
+function ensureTelegramGroupRoute(config, chatId) {
+  const existing = config.channels.telegram.groups[chatId];
+  if (existing) {
+    return existing;
+  }
+  const created = createTelegramGroupRoute();
+  config.channels.telegram.groups[chatId] = created;
+  return created;
+}
+function ensureTelegramTopicRoute(config, chatId, topicId) {
+  const group = ensureTelegramGroupRoute(config, chatId);
+  const existing = group.topics[topicId];
+  if (existing) {
+    return existing;
+  }
+  const created = {};
+  group.topics[topicId] = created;
+  return created;
+}
 function getModeValue(source, field) {
   return source[field];
 }
 function setModeValue(source, field, value) {
   source[field] = value;
 }
+var EMPTY_MODE_SOURCE = {};
 function resolveSlackConfigTarget(config, field, params) {
   if (!params.target) {
     return {
@@ -62820,22 +63207,25 @@ function resolveTelegramConfigTarget(config, field, params) {
     };
   }
   const group = config.channels.telegram.groups[chatId];
-  if (!group) {
-    throw new Error(renderTelegramRouteChoiceMessage({ chatId }));
-  }
   if (topicId) {
-    const topic = group.topics?.[topicId];
-    if (!topic) {
-      throw new Error(renderTelegramRouteChoiceMessage({ chatId, topicId }));
-    }
+    const topic = group?.topics?.[topicId];
     return {
-      get: () => getModeValue(topic, field) ?? getModeValue(group, field) ?? getModeValue(config.channels.telegram, field),
+      get: () => getModeValue(topic ?? EMPTY_MODE_SOURCE, field) ?? getModeValue(group ?? EMPTY_MODE_SOURCE, field) ?? getModeValue(config.channels.telegram, field),
       set: (value) => {
-        setModeValue(topic, field, value);
+        setModeValue(ensureTelegramTopicRoute(config, chatId, topicId), field, value);
       },
       label: `telegram topic ${chatId}/${topicId}`
     };
   }
+  if (!group) {
+    return {
+      get: () => getModeValue(config.channels.telegram, field),
+      set: (value) => {
+        setModeValue(ensureTelegramGroupRoute(config, chatId), field, value);
+      },
+      label: `telegram group ${chatId}`
+    };
+  }
   return {
     get: () => getModeValue(group, field) ?? getModeValue(config.channels.telegram, field),
     set: (value) => {
@@ -62876,11 +63266,11 @@ function renderFieldLabel(field) {
 }
 
 // src/channels/additional-message-mode-config.ts
-function getEditableConfigPath3() {
+function getEditableConfigPath4() {
   return process.env.CLISBOT_CONFIG_PATH;
 }
 async function getConversationAdditionalMessageMode(params) {
-  const { config } = await readEditableConfig(getEditableConfigPath3());
+  const { config } = await readEditableConfig(getEditableConfigPath4());
   const target = resolveConfiguredSurfaceModeTarget(config, "additionalMessageMode", buildConfiguredTargetFromIdentity(params.identity));
   return {
     label: target.label,
@@ -62888,7 +63278,7 @@ async function getConversationAdditionalMessageMode(params) {
   };
 }
 async function setConversationAdditionalMessageMode(params) {
-  const { config, configPath } = await readEditableConfig(getEditableConfigPath3());
+  const { config, configPath } = await readEditableConfig(getEditableConfigPath4());
   const target = resolveConfiguredSurfaceModeTarget(config, "additionalMessageMode", buildConfiguredTargetFromIdentity(params.identity));
   target.set(params.additionalMessageMode);
   await writeEditableConfig(configPath, config);
@@ -62899,7 +63289,7 @@ async function setConversationAdditionalMessageMode(params) {
   };
 }
 async function getConfiguredAdditionalMessageMode(params) {
-  const { config, configPath } = await readEditableConfig(getEditableConfigPath3());
+  const { config, configPath } = await readEditableConfig(getEditableConfigPath4());
   const target = resolveConfiguredSurfaceModeTarget(config, "additionalMessageMode", params);
   return {
     configPath,
@@ -62908,7 +63298,7 @@ async function getConfiguredAdditionalMessageMode(params) {
   };
 }
 async function setConfiguredAdditionalMessageMode(params) {
-  const { config, configPath } = await readEditableConfig(getEditableConfigPath3());
+  const { config, configPath } = await readEditableConfig(getEditableConfigPath4());
   const target = resolveConfiguredSurfaceModeTarget(config, "additionalMessageMode", params);
   target.set(params.additionalMessageMode);
   await writeEditableConfig(configPath, config);
@@ -62920,11 +63310,11 @@ async function setConfiguredAdditionalMessageMode(params) {
 }
 
 // src/channels/response-mode-config.ts
-function getEditableConfigPath4() {
+function getEditableConfigPath5() {
   return process.env.CLISBOT_CONFIG_PATH;
 }
 async function getConversationResponseMode(params) {
-  const { config } = await readEditableConfig(getEditableConfigPath4());
+  const { config } = await readEditableConfig(getEditableConfigPath5());
   const target = resolveConfiguredSurfaceModeTarget(config, "responseMode", buildConfiguredTargetFromIdentity(params.identity));
   return {
     label: target.label,
@@ -62932,7 +63322,7 @@ async function getConversationResponseMode(params) {
   };
 }
 async function setConversationResponseMode(params) {
-  const { config, configPath } = await readEditableConfig(getEditableConfigPath4());
+  const { config, configPath } = await readEditableConfig(getEditableConfigPath5());
   const target = resolveConfiguredSurfaceModeTarget(config, "responseMode", buildConfiguredTargetFromIdentity(params.identity));
   target.set(params.responseMode);
   await writeEditableConfig(configPath, config);
@@ -62943,7 +63333,7 @@ async function setConversationResponseMode(params) {
   };
 }
 async function getConfiguredResponseMode(params) {
-  const { config, configPath } = await readEditableConfig(getEditableConfigPath4());
+  const { config, configPath } = await readEditableConfig(getEditableConfigPath5());
   const target = resolveConfiguredSurfaceModeTarget(config, "responseMode", params);
   return {
     configPath,
@@ -62952,7 +63342,7 @@ async function getConfiguredResponseMode(params) {
   };
 }
 async function setConfiguredResponseMode(params) {
-  const { config, configPath } = await readEditableConfig(getEditableConfigPath4());
+  const { config, configPath } = await readEditableConfig(getEditableConfigPath5());
   const target = resolveConfiguredSurfaceModeTarget(config, "responseMode", params);
   target.set(params.responseMode);
   await writeEditableConfig(configPath, config);
@@ -62978,7 +63368,7 @@ async function runChannelPrivilegeCli(_args) {
 
 // src/control/channels-cli.ts
 var AUTH_USER_GUIDE_DOC_PATH = "docs/user-guide/auth-and-roles.md";
-function getEditableConfigPath5() {
+function getEditableConfigPath6() {
   return process.env.CLISBOT_CONFIG_PATH;
 }
 function renderChannelsHelp() {
@@ -63127,7 +63517,7 @@ function getAgentId(args) {
   return parseOptionValue2(args, "--agent") ?? "default";
 }
 async function setChannelEnabled(action, channel) {
-  const { config, configPath } = await readEditableConfig(getEditableConfigPath5());
+  const { config, configPath } = await readEditableConfig(getEditableConfigPath6());
   const enabled = action === "enable";
   const current = config.channels[channel].enabled;
   if (current === enabled) {
@@ -63147,7 +63537,7 @@ async function addTelegramGroup(args) {
   if (!chatId) {
     throw new Error("Usage: clisbot channels add telegram-group <chatId> [--topic <topicId>] [--agent <id>] [--require-mention true|false]");
   }
-  const { config, configPath } = await readEditableConfig(getEditableConfigPath5());
+  const { config, configPath } = await readEditableConfig(getEditableConfigPath6());
   const topicId = parseOptionValue2(args, "--topic");
   const agentId = getAgentId(args);
   const requireMention = parseBooleanOption(args, "--require-mention", true);
@@ -63200,7 +63590,7 @@ async function removeTelegramGroup(args) {
   if (!chatId) {
     throw new Error("Usage: clisbot channels remove telegram-group <chatId> [--topic <topicId>]");
   }
-  const { config, configPath } = await readEditableConfig(getEditableConfigPath5());
+  const { config, configPath } = await readEditableConfig(getEditableConfigPath6());
   const topicId = parseOptionValue2(args, "--topic");
   const groupRoute = config.channels.telegram.groups[chatId];
   if (!groupRoute) {
@@ -63230,7 +63620,7 @@ async function addSlackRoute(kind, args) {
   if (!routeId) {
     throw new Error(`Usage: clisbot channels add slack-${kind} <${kind}Id> [--agent <id>] [--require-mention true|false]`);
   }
-  const { config, configPath } = await readEditableConfig(getEditableConfigPath5());
+  const { config, configPath } = await readEditableConfig(getEditableConfigPath6());
   const agentId = getAgentId(args);
   const requireMention = parseBooleanOption(args, "--require-mention", false);
   const target = kind === "channel" ? config.channels.slack.channels : config.channels.slack.groups;
@@ -63254,7 +63644,7 @@ async function removeSlackRoute(kind, args) {
   if (!routeId) {
     throw new Error(`Usage: clisbot channels remove slack-${kind} <${kind}Id>`);
   }
-  const { config, configPath } = await readEditableConfig(getEditableConfigPath5());
+  const { config, configPath } = await readEditableConfig(getEditableConfigPath6());
   const target = kind === "channel" ? config.channels.slack.channels : config.channels.slack.groups;
   if (!target[routeId]) {
     console.log(`slack ${kind} route ${routeId} is not configured`);
@@ -63267,7 +63657,7 @@ async function removeSlackRoute(kind, args) {
   console.log(`config: ${configPath}`);
 }
 async function setToken(target, value) {
-  const { config, configPath } = await readEditableConfig(getEditableConfigPath5());
+  const { config, configPath } = await readEditableConfig(getEditableConfigPath6());
   if (target === "slack-app") {
     config.channels.slack.appToken = value;
     const defaultAccountId = config.channels.slack.defaultAccount || "default";
@@ -63299,7 +63689,7 @@ async function setToken(target, value) {
   console.log(`config: ${configPath}`);
 }
 async function clearToken(target) {
-  const { config, configPath } = await readEditableConfig(getEditableConfigPath5());
+  const { config, configPath } = await readEditableConfig(getEditableConfigPath6());
   if (target === "slack-app") {
     config.channels.slack.appToken = "";
     const defaultAccountId = config.channels.slack.defaultAccount || "default";
@@ -64038,7 +64428,7 @@ class SessionStore {
 }
 
 // src/control/loops-cli.ts
-function getEditableConfigPath6() {
+function getEditableConfigPath7() {
   return process.env.CLISBOT_CONFIG_PATH;
 }
 function renderLoopsHelp() {
@@ -64096,7 +64486,7 @@ function getSessionState(sessionStorePath) {
   return new AgentSessionState(new SessionStore(sessionStorePath));
 }
 async function loadLoopControlState() {
-  const configPath = await ensureEditableConfigFile(getEditableConfigPath6());
+  const configPath = await ensureEditableConfigFile(getEditableConfigPath7());
   const loadedConfig = await loadConfigWithoutEnvResolution(configPath);
   const sessionStorePath = resolveSessionStorePath(loadedConfig);
   return {
@@ -64272,6 +64662,9 @@ function buildReplyCommand(params) {
   const lines = [`${params.command} message send \\`];
   if (params.identity.platform === "slack") {
     lines.push("  --channel slack \\");
+    if (params.identity.accountId) {
+      lines.push(`  --account ${params.identity.accountId} \\`);
+    }
     lines.push(`  --target channel:${params.identity.channelId ?? ""} \\`);
     if (params.identity.threadTs) {
       lines.push(`  --thread-id ${params.identity.threadTs} \\`);
@@ -64286,6 +64679,9 @@ function buildReplyCommand(params) {
 `);
   }
   lines.push("  --channel telegram \\");
+  if (params.identity.accountId) {
+    lines.push(`  --account ${params.identity.accountId} \\`);
+  }
   lines.push(`  --target ${params.identity.chatId ?? ""} \\`);
   if (params.identity.topicId) {
     lines.push(`  --thread-id ${params.identity.topicId} \\`);
@@ -64300,6 +64696,57 @@ function buildReplyCommand(params) {
 `);
 }
 
+// src/channels/surface-notifications.ts
+function sanitizeInlineCode(text) {
+  return text.replaceAll("`", "'");
+}
+function summarizeSurfaceNotificationText(text, maxLength = 60) {
+  const singleLine = sanitizeInlineCode(text.replace(/\s+/g, " ").trim());
+  if (!singleLine) {
+    return "(empty)";
+  }
+  if (singleLine.length <= maxLength) {
+    return singleLine;
+  }
+  return `${singleLine.slice(0, maxLength - 3)}...`;
+}
+function renderQueueStartNotification(params) {
+  if (params.mode === "none") {
+    return;
+  }
+  const summary = summarizeSurfaceNotificationText(params.promptSummary);
+  if (params.mode === "full") {
+    return `Queued message is now running for agent \`${params.agentId}\`: \`${summary}\`.`;
+  }
+  return `Queued message is now running: \`${summary}\`.`;
+}
+function renderLoopScheduleSegment(params) {
+  if (params.kind === "calendar") {
+    return formatCalendarLoopSchedule({
+      cadence: params.cadence,
+      dayOfWeek: params.dayOfWeek,
+      localTime: params.localTime
+    });
+  }
+  return `every ${formatLoopIntervalShort(params.intervalMs)}`;
+}
+function renderLoopStartNotification(params) {
+  if (params.mode === "none") {
+    return;
+  }
+  const summary = summarizeSurfaceNotificationText(params.promptSummary);
+  const segments = [
+    `\`${summary}\``,
+    renderLoopScheduleSegment(params),
+    `next run \`${new Date(params.nextRunAt).toISOString()}\``,
+    `remaining \`${params.remainingRuns}/${params.maxRuns}\``
+  ];
+  if (params.mode === "full") {
+    return `Loop \`${params.loopId}\` is now running for agent \`${params.agentId}\`: ${segments.join(" · ")}.`;
+  }
+  return `Loop \`${params.loopId}\` is now running: ${segments.join(" · ")}.`;
+}
+
 // src/agents/session-key.ts
 var DEFAULT_MAIN_KEY = "main";
 var DEFAULT_ACCOUNT_ID = "default";
@@ -66583,6 +67030,7 @@ class AgentService {
   cleanupTimer;
   loopTimers = new Set;
   intervalLoops = new Map;
+  surfaceNotificationHandlers = new Map;
   constructor(loadedConfig, deps = {}) {
     this.loadedConfig = loadedConfig;
     this.tmuxClient = deps.tmux ?? new TmuxClient(this.loadedConfig.raw.tmux.socketPath);
@@ -66611,7 +67059,9 @@ class AgentService {
     }
     await this.runnerSessions.runSessionCleanup();
     this.cleanupTimer = setInterval(() => {
-      this.runnerSessions.runSessionCleanup();
+      this.runnerSessions.runSessionCleanup().catch((error) => {
+        console.error("session cleanup failed", error);
+      });
     }, cleanup.intervalMinutes * 60000);
   }
   async stop() {
@@ -66635,6 +67085,12 @@ class AgentService {
   async cleanupStaleSessions() {
     await this.runnerSessions.runSessionCleanup();
   }
+  registerSurfaceNotificationHandler(params) {
+    this.surfaceNotificationHandlers.set(this.getSurfaceNotificationHandlerKey(params.platform, params.accountId), params.handler);
+  }
+  unregisterSurfaceNotificationHandler(params) {
+    this.surfaceNotificationHandlers.delete(this.getSurfaceNotificationHandlerKey(params.platform, params.accountId));
+  }
   resolveTarget(target) {
     return resolveAgentTarget(this.loadedConfig, target);
   }
@@ -66743,7 +67199,9 @@ class AgentService {
       target: params.target,
       loop
     });
-    await this.runIntervalLoopIteration(loop.id);
+    await this.runIntervalLoopIteration(loop.id, {
+      notifyStart: false
+    });
     return this.getIntervalLoop(loop.id);
   }
   async createCalendarLoop(params) {
@@ -66905,7 +67363,7 @@ class AgentService {
     }
     this.intervalLoops.delete(loopId);
   }
-  async runIntervalLoopIteration(loopId) {
+  async runIntervalLoopIteration(loopId, options = {}) {
     const managed = this.intervalLoops.get(loopId);
     if (!managed) {
       return;
@@ -66941,6 +67399,9 @@ class AgentService {
       this.dropManagedIntervalLoop(loopId);
       return;
     }
+    if (options.notifyStart !== false) {
+      await this.notifyManagedLoopStart(managed.target, nextLoopState);
+    }
     const promptText = this.buildManagedLoopPrompt(managed.target.agentId, nextLoopState);
     const { result } = this.enqueuePrompt(managed.target, promptText, {
       observerId: `loop:${loopId}:${attemptedRuns}`,
@@ -66960,6 +67421,101 @@ class AgentService {
     }
     this.scheduleIntervalLoopTimer(loopId, Math.max(0, nextLoopState.nextRunAt - now));
   }
+  getSurfaceNotificationHandlerKey(platform, accountId) {
+    return `${platform}:${accountId?.trim() || "default"}`;
+  }
+  async notifySurface(request) {
+    const handler = this.surfaceNotificationHandlers.get(this.getSurfaceNotificationHandlerKey(request.binding.platform, request.binding.accountId));
+    if (!handler) {
+      return;
+    }
+    await handler(request);
+  }
+  resolveLoopSurfaceNotifications(identity) {
+    if (identity.platform === "slack") {
+      const channelConfig2 = this.loadedConfig.raw.channels.slack;
+      let resolved2 = {
+        queueStart: channelConfig2.surfaceNotifications?.queueStart ?? "brief",
+        loopStart: channelConfig2.surfaceNotifications?.loopStart ?? "brief"
+      };
+      if (identity.conversationKind === "dm") {
+        return {
+          ...resolved2,
+          ...channelConfig2.directMessages.surfaceNotifications ?? {}
+        };
+      }
+      const routeCollection = identity.conversationKind === "group" ? channelConfig2.groups : channelConfig2.channels;
+      const route = identity.channelId ? routeCollection[identity.channelId] ?? routeCollection["*"] : undefined;
+      return {
+        ...resolved2,
+        ...route?.surfaceNotifications ?? {}
+      };
+    }
+    const channelConfig = this.loadedConfig.raw.channels.telegram;
+    let resolved = {
+      queueStart: channelConfig.surfaceNotifications?.queueStart ?? "brief",
+      loopStart: channelConfig.surfaceNotifications?.loopStart ?? "brief"
+    };
+    if (identity.conversationKind === "dm") {
+      return {
+        ...resolved,
+        ...channelConfig.directMessages.surfaceNotifications ?? {}
+      };
+    }
+    const groupRoute = identity.chatId ? channelConfig.groups[identity.chatId] ?? channelConfig.groups["*"] : undefined;
+    resolved = {
+      ...resolved,
+      ...groupRoute?.surfaceNotifications ?? {}
+    };
+    if (identity.conversationKind === "topic" && identity.topicId) {
+      return {
+        ...resolved,
+        ...groupRoute?.topics?.[identity.topicId]?.surfaceNotifications ?? {}
+      };
+    }
+    return resolved;
+  }
+  async notifyManagedLoopStart(target, loop) {
+    if (!loop.surfaceBinding) {
+      return;
+    }
+    const identity = this.buildLoopChannelIdentity(loop.surfaceBinding);
+    const notifications = this.resolveLoopSurfaceNotifications(identity);
+    const text = loop.kind === "calendar" ? renderLoopStartNotification({
+      mode: notifications.loopStart,
+      agentId: target.agentId,
+      loopId: loop.id,
+      promptSummary: loop.promptSummary,
+      cadence: loop.cadence,
+      dayOfWeek: loop.dayOfWeek,
+      localTime: loop.localTime,
+      timezone: loop.timezone,
+      nextRunAt: loop.nextRunAt,
+      remainingRuns: Math.max(0, loop.maxRuns - loop.attemptedRuns),
+      maxRuns: loop.maxRuns,
+      kind: "calendar"
+    }) : renderLoopStartNotification({
+      mode: notifications.loopStart,
+      agentId: target.agentId,
+      loopId: loop.id,
+      promptSummary: loop.promptSummary,
+      intervalMs: loop.intervalMs,
+      nextRunAt: loop.nextRunAt,
+      remainingRuns: Math.max(0, loop.maxRuns - loop.attemptedRuns),
+      maxRuns: loop.maxRuns
+    });
+    if (!text) {
+      return;
+    }
+    try {
+      await this.notifySurface({
+        binding: loop.surfaceBinding,
+        text
+      });
+    } catch (error) {
+      console.error("loop start notification failed", error);
+    }
+  }
   scheduleIntervalLoopTimer(loopId, delayMs) {
     const managed = this.intervalLoops.get(loopId);
     if (!managed) {
@@ -66976,7 +67532,9 @@ class AgentService {
         return;
       }
       current.timer = undefined;
-      this.runIntervalLoopIteration(loopId).catch((error) => {
+      this.runIntervalLoopIteration(loopId, {
+        notifyStart: true
+      }).catch((error) => {
         if (this.shouldSuppressLoopShutdownError(error)) {
           return;
         }
@@ -67034,6 +67592,7 @@ class AgentService {
   buildLoopChannelIdentity(binding) {
     return {
       platform: binding.platform,
+      accountId: binding.accountId,
       conversationKind: binding.conversationKind,
       channelId: binding.channelId,
       chatId: binding.chatId,
@@ -67649,11 +68208,11 @@ function formatChannelFollowUpStatus(params) {
 }
 
 // src/channels/streaming-config.ts
-function getEditableConfigPath7() {
+function getEditableConfigPath8() {
   return process.env.CLISBOT_CONFIG_PATH;
 }
 async function getConversationStreaming(params) {
-  const { config } = await readEditableConfig(getEditableConfigPath7());
+  const { config } = await readEditableConfig(getEditableConfigPath8());
   const target = resolveConfiguredSurfaceModeTarget(config, "streaming", buildConfiguredTargetFromIdentity(params.identity));
   return {
     label: target.label,
@@ -67661,7 +68220,7 @@ async function getConversationStreaming(params) {
   };
 }
 async function setConversationStreaming(params) {
-  const { config, configPath } = await readEditableConfig(getEditableConfigPath7());
+  const { config, configPath } = await readEditableConfig(getEditableConfigPath8());
   const target = resolveConfiguredSurfaceModeTarget(config, "streaming", buildConfiguredTargetFromIdentity(params.identity));
   target.set(params.streaming);
   await writeEditableConfig(configPath, config);
@@ -67742,7 +68301,7 @@ function renderRouteStatusMessage(params) {
   if (params.identity.topicId) {
     lines.push(`topicId: \`${params.identity.topicId}\``);
   }
-  lines.push(`streaming: \`${params.route.streaming}\``, `response: \`${params.route.response}\``, `responseMode: \`${params.route.responseMode}\``, `additionalMessageMode: \`${params.route.additionalMessageMode}\``, `verbose: \`${params.route.verbose}\``, `principal: \`${params.auth.principal ?? "(none)"}\``, `appRole: \`${params.auth.appRole}\``, `agentRole: \`${params.auth.agentRole}\``, `mayManageProtectedResources: \`${params.auth.mayManageProtectedResources}\``, `canUseShell: \`${params.auth.canUseShell}\``, `timezone: \`${params.route.timezone ?? "(inherit host/app)"}\``, `followUp.mode: \`${params.followUpState.overrideMode ?? params.route.followUp.mode}\``, `followUp.windowMinutes: \`${formatFollowUpTtlMinutes(params.route.followUp.participationTtlMs)}\``, `run.state: \`${params.runtimeState.state}\``);
+  lines.push(`streaming: \`${params.route.streaming}\``, `response: \`${params.route.response}\``, `responseMode: \`${params.route.responseMode}\``, `additionalMessageMode: \`${params.route.additionalMessageMode}\``, `surfaceNotifications.queueStart: \`${params.route.surfaceNotifications.queueStart}\``, `surfaceNotifications.loopStart: \`${params.route.surfaceNotifications.loopStart}\``, `verbose: \`${params.route.verbose}\``, `principal: \`${params.auth.principal ?? "(none)"}\``, `appRole: \`${params.auth.appRole}\``, `agentRole: \`${params.auth.agentRole}\``, `mayManageProtectedResources: \`${params.auth.mayManageProtectedResources}\``, `canUseShell: \`${params.auth.canUseShell}\``, `timezone: \`${params.route.timezone ?? "(inherit host/app)"}\``, `followUp.mode: \`${params.followUpState.overrideMode ?? params.route.followUp.mode}\``, `followUp.windowMinutes: \`${formatFollowUpTtlMinutes(params.route.followUp.participationTtlMs)}\``, `run.state: \`${params.runtimeState.state}\``);
   if (params.runtimeState.startedAt) {
     lines.push(`run.startedAt: \`${new Date(params.runtimeState.startedAt).toISOString()}\``);
   }
@@ -67979,6 +68538,7 @@ async function resolveLoopPromptText(params) {
 function buildLoopSurfaceBinding(identity) {
   return {
     platform: identity.platform,
+    accountId: identity.accountId,
     conversationKind: identity.conversationKind,
     channelId: identity.channelId,
     chatId: identity.chatId,
@@ -67995,6 +68555,8 @@ async function executePromptDelivery(params) {
   let loggedFirstRunningUpdate = false;
   let activePreviewStartedAt;
   let messageToolPreviewHandedOff = false;
+  let queueStartPending = false;
+  let deferredQueueStartPreview = false;
   const paneManagedDelivery = params.route.responseMode === "capture-pane" || params.forceQueuedDelivery === true;
   const messageToolPreview = params.route.responseMode === "message-tool" && params.forceQueuedDelivery !== true && params.route.streaming !== "off";
   const previewEnabled = params.route.streaming !== "off" && (paneManagedDelivery || messageToolPreview);
@@ -68069,6 +68631,68 @@ async function executePromptDelivery(params) {
     agentId: params.route.agentId,
     sessionKey: params.sessionTarget.sessionKey
   });
+  async function maybeRenderQueueStartNotification() {
+    if (!queueStartPending) {
+      return false;
+    }
+    const text = renderQueueStartNotification({
+      mode: params.queueStartMode ?? "none",
+      agentId: params.route.agentId,
+      promptSummary: params.notificationPromptSummary ?? summarizeSurfaceNotificationText(params.promptText)
+    });
+    if (!text) {
+      queueStartPending = false;
+      return false;
+    }
+    if (previewEnabled && responseChunks.length === 0) {
+      deferredQueueStartPreview = true;
+      return true;
+    }
+    queueStartPending = false;
+    if (responseChunks.length > 0) {
+      const postedNew = await renderResponseText(text);
+      if (postedNew) {
+        await recordVisibleReply("reply", "channel");
+        activePreviewStartedAt = Date.now();
+      }
+      renderedState = {
+        text,
+        body: ""
+      };
+      return true;
+    }
+    const posted = await params.postText(text);
+    if (posted.length > 0) {
+      await recordVisibleReply("reply", "channel");
+    }
+    return posted.length > 0;
+  }
+  function buildInitialPlaceholderText(positionAhead) {
+    if (deferredQueueStartPreview && queueStartPending) {
+      deferredQueueStartPreview = false;
+      queueStartPending = false;
+      return renderQueueStartNotification({
+        mode: params.queueStartMode ?? "none",
+        agentId: params.route.agentId,
+        promptSummary: params.notificationPromptSummary ?? summarizeSurfaceNotificationText(params.promptText)
+      }) ?? renderPlatformInteraction({
+        platform: params.identity.platform,
+        status: positionAhead > 0 ? "queued" : "running",
+        content: "",
+        queuePosition: positionAhead,
+        maxChars: Number.POSITIVE_INFINITY,
+        note: positionAhead > 0 ? "Waiting for the agent queue to clear." : "Working..."
+      });
+    }
+    return renderPlatformInteraction({
+      platform: params.identity.platform,
+      status: positionAhead > 0 ? "queued" : "running",
+      content: "",
+      queuePosition: positionAhead,
+      maxChars: Number.POSITIVE_INFINITY,
+      note: positionAhead > 0 ? "Waiting for the agent queue to clear." : "Working..."
+    });
+  }
   try {
     const { positionAhead, result } = params.agentService.enqueuePrompt(params.sessionTarget, params.promptText, {
       observerId: params.observerId,
@@ -68077,9 +68701,6 @@ async function executePromptDelivery(params) {
         if (!paneManagedDelivery && !messageToolPreview) {
           return;
         }
-        if (params.route.streaming === "off" && update.status === "running") {
-          return;
-        }
         if (update.status === "running" && !loggedFirstRunningUpdate) {
           loggedFirstRunningUpdate = true;
           logLatencyDebug("channel-first-running-update", params.timingContext, {
@@ -68088,14 +68709,21 @@ async function executePromptDelivery(params) {
           });
         }
         await (renderChain = renderChain.then(async () => {
+          let renderedQueueStart = false;
+          if (update.status === "running") {
+            renderedQueueStart = await maybeRenderQueueStartNotification();
+          }
+          if (params.route.streaming === "off" && update.status === "running") {
+            return;
+          }
+          if (renderedQueueStart) {
+            return;
+          }
           const signals = await getMessageToolRuntimeSignals();
           if (messageToolPreview && typeof activePreviewStartedAt === "number" && (typeof signals.messageToolFinalReplyAt === "number" && signals.messageToolFinalReplyAt >= activePreviewStartedAt || typeof signals.lastMessageToolReplyAt === "number" && signals.lastMessageToolReplyAt >= activePreviewStartedAt)) {
             await handoffMessageToolPreview();
             return;
           }
-          if (messageToolPreview) {
-            return;
-          }
           const nextState2 = buildRenderedMessageState({
             platform: params.identity.platform,
             status: update.status,
@@ -68119,15 +68747,9 @@ async function executePromptDelivery(params) {
         }));
       }
     });
+    queueStartPending = positionAhead > 0 && (params.queueStartMode ?? "none") !== "none";
     if (previewEnabled) {
-      const placeholderText = renderPlatformInteraction({
-        platform: params.identity.platform,
-        status: positionAhead > 0 ? "queued" : "running",
-        content: "",
-        queuePosition: positionAhead,
-        maxChars: Number.POSITIVE_INFINITY,
-        note: positionAhead > 0 ? "Waiting for the agent queue to clear." : "Working..."
-      });
+      const placeholderText = buildInitialPlaceholderText(positionAhead);
       const postedNew2 = await renderResponseText(placeholderText);
       if (postedNew2) {
         await recordVisibleReply("reply", "channel");
@@ -68157,6 +68779,7 @@ async function executePromptDelivery(params) {
     }
     const finalResult = await result;
     await renderChain;
+    await maybeRenderQueueStartNotification();
     if (!paneManagedDelivery && messageToolPreviewHandedOff) {
       return;
     }
@@ -68641,6 +69264,8 @@ ${renderLoopUsage()}`);
           route: params.route,
           maxChars: params.maxChars,
           promptText: buildLoopPromptText(resolvedLoopPrompt.text),
+          queueStartMode: params.route.surfaceNotifications.queueStart,
+          notificationPromptSummary: summarizeLoopPrompt(resolvedLoopPrompt.text, resolvedLoopPrompt.maintenancePrompt),
           postText: params.postText,
           reconcileText: params.reconcileText,
           observerId: `${observerId}:loop:${index + 1}`
@@ -68781,6 +69406,8 @@ ${escapeCodeFence(shellResult.output)}
     route: params.route,
     maxChars: params.maxChars,
     promptText: delayedPromptText,
+    queueStartMode: params.route.surfaceNotifications.queueStart,
+    notificationPromptSummary: explicitQueueMessage ?? summarizeSurfaceNotificationText(params.text),
     postText: params.postText,
     reconcileText: params.reconcileText,
     observerId,
@@ -68841,6 +69468,23 @@ function isTelegramSenderAllowed(params) {
 }
 
 // src/auth/resolve.ts
+function mergeRoleDefinitions2(inherited, override) {
+  return {
+    allow: override?.allow ?? inherited?.allow ?? [],
+    users: override?.users ?? inherited?.users ?? []
+  };
+}
+function mergeRoleRecord2(defaults, overrides) {
+  const merged = {};
+  const roleNames = new Set([
+    ...Object.keys(defaults ?? {}),
+    ...Object.keys(overrides ?? {})
+  ]);
+  for (const roleName of roleNames) {
+    merged[roleName] = mergeRoleDefinitions2(defaults?.[roleName], overrides?.[roleName]);
+  }
+  return merged;
+}
 function normalizePrincipal(principal) {
   const trimmed = principal.trim();
   if (!trimmed) {
@@ -68888,10 +69532,7 @@ function getAgentAuth(config, agentId) {
   const override = entry?.auth;
   return {
     defaultRole: override?.defaultRole ?? defaults.defaultRole,
-    roles: {
-      ...defaults.roles,
-      ...override?.roles ?? {}
-    }
+    roles: mergeRoleRecord2(defaults.roles, override?.roles)
   };
 }
 function getAllowedPermissions(roles, role) {
@@ -69014,6 +69655,10 @@ function buildSharedChannelRoute(params) {
     response: params.route?.response ?? params.channelConfig.response,
     responseMode: params.route?.responseMode ?? agentEntry?.responseMode ?? params.channelConfig.responseMode,
     additionalMessageMode: params.route?.additionalMessageMode ?? agentEntry?.additionalMessageMode ?? params.channelConfig.additionalMessageMode,
+    surfaceNotifications: {
+      queueStart: params.route?.surfaceNotifications?.queueStart ?? params.channelConfig.surfaceNotifications?.queueStart ?? "brief",
+      loopStart: params.route?.surfaceNotifications?.loopStart ?? params.channelConfig.surfaceNotifications?.loopStart ?? "brief"
+    },
     verbose: params.route?.verbose ?? params.channelConfig.verbose,
     followUp: {
       mode: params.route?.followUp?.mode ?? params.channelConfig.followUp.mode,
@@ -69990,6 +70635,20 @@ class SlackSocketService {
       appToken: this.accountConfig.appToken,
       socketMode: true
     });
+    this.agentService.registerSurfaceNotificationHandler({
+      platform: "slack",
+      accountId: this.accountId,
+      handler: async ({ binding, text }) => {
+        if (!binding.channelId) {
+          return;
+        }
+        await postSlackText(this.app.client, {
+          channel: binding.channelId,
+          threadTs: binding.threadTs,
+          text
+        });
+      }
+    });
     this.registerEvents();
   }
   getSlackMaxChars(agentId) {
@@ -70243,6 +70902,7 @@ class SlackSocketService {
     const cliTool = getAgentEntry(this.loadedConfig, params.route.agentId)?.cliTool;
     const identity = {
       platform: "slack",
+      accountId: this.accountId,
       conversationKind: params.conversationKind,
       senderId: typeof event.user === "string" ? event.user.trim().toUpperCase() : undefined,
       channelId,
@@ -70426,6 +71086,10 @@ class SlackSocketService {
     await this.startPromise;
   }
   async stop() {
+    this.agentService.unregisterSurfaceNotificationHandler({
+      platform: "slack",
+      accountId: this.accountId
+    });
     await this.app.stop();
   }
   getBotUserLabel() {
@@ -71280,6 +71944,33 @@ async function resolveTelegramAttachmentPaths(params) {
   return attachmentPaths;
 }
 
+// src/channels/telegram/route-guidance.ts
+function renderTelegramRouteChoiceMessage(params) {
+  const chatId = String(params.chatId);
+  const topicId = params.topicId != null ? String(params.topicId) : undefined;
+  const lines = [
+    topicId != null ? "clisbot: this Telegram topic is not configured yet." : "clisbot: this Telegram group is not configured yet.",
+    "",
+    "Ask the bot owner to choose one of these:",
+    "",
+    "Add the whole group with the default agent:",
+    `\`clisbot channels add telegram-group ${chatId}\``,
+    "",
+    "Add the whole group with a specific agent:",
+    `\`clisbot channels add telegram-group ${chatId} --agent <id>\``
+  ];
+  if (topicId != null) {
+    lines.push("", "Add only this topic with a specific agent:", `\`clisbot channels add telegram-group ${chatId} --topic ${topicId} --agent <id>\``);
+  }
+  if (params.includeConfigPath) {
+    lines.push("", topicId != null ? `Config path: \`channels.telegram.groups."${chatId}".topics."${topicId}"\`` : `Config path: \`channels.telegram.groups."${chatId}"\``);
+  } else {
+    lines.push("", "After that, routed commands such as `/status`, `/stop`, `/nudge`, `/followup`, and `/bash` will work here.");
+  }
+  return lines.join(`
+`);
+}
+
 // src/channels/telegram/typing.ts
 var TELEGRAM_TYPING_HEARTBEAT_MS = 4500;
 function logTelegramTypingError(onError, error) {
@@ -71423,6 +72114,7 @@ class TelegramPollingService {
   activityStore;
   accountId;
   accountConfig;
+  reportLifecycle;
   botUserId = 0;
   botUsername = "";
   running = false;
@@ -71431,13 +72123,35 @@ class TelegramPollingService {
   activePollController;
   inFlightUpdates = new Set;
   processingIndicators = new ConversationProcessingIndicatorCoordinator;
-  constructor(loadedConfig, agentService, processedEventsStore, activityStore, accountId = "default", accountConfig) {
+  constructor(loadedConfig, agentService, processedEventsStore, activityStore, accountId = "default", accountConfig, reportLifecycle) {
     this.loadedConfig = loadedConfig;
     this.agentService = agentService;
     this.processedEventsStore = processedEventsStore;
     this.activityStore = activityStore;
     this.accountId = accountId;
     this.accountConfig = accountConfig;
+    this.reportLifecycle = reportLifecycle;
+    this.agentService.registerSurfaceNotificationHandler({
+      platform: "telegram",
+      accountId: this.accountId,
+      handler: async ({ binding, text }) => {
+        if (!binding.chatId) {
+          return;
+        }
+        const chatId = Number(binding.chatId);
+        if (!Number.isFinite(chatId)) {
+          return;
+        }
+        const topicId = binding.topicId ? Number(binding.topicId) : undefined;
+        await postTelegramText({
+          token: this.accountConfig.botToken,
+          chatId,
+          text,
+          topicId: Number.isFinite(topicId) ? topicId : undefined,
+          omitThreadId: shouldOmitTelegramThreadId(Number.isFinite(topicId) ? topicId : undefined)
+        });
+      }
+    });
   }
   async start() {
     const me = await callTelegramApi(this.accountConfig.botToken, "getMe", {});
@@ -71454,6 +72168,10 @@ class TelegramPollingService {
     this.activePollController?.abort();
     await this.loopPromise;
     await Promise.allSettled([...this.inFlightUpdates]);
+    this.agentService.unregisterSurfaceNotificationHandler({
+      platform: "telegram",
+      accountId: this.accountId
+    });
   }
   getBotLabel() {
     return this.botUsername ? `@${this.botUsername}` : `${this.botUserId || "unknown"}`;
@@ -71500,6 +72218,15 @@ class TelegramPollingService {
         }
         if (isTelegramPollingConflict(error)) {
           this.running = false;
+          await this.reportLifecycle?.({
+            connection: "failed",
+            summary: "Telegram polling stopped because another instance is already using this bot token.",
+            detail: error instanceof Error ? error.message : String(error),
+            actions: [
+              "stop the other Telegram poller that is using the same bot token",
+              "run `clisbot start` again after the token is no longer in use elsewhere"
+            ]
+          });
           console.error("telegram polling stopped: another bot instance is already calling getUpdates for this token");
           return;
         }
@@ -71667,6 +72394,7 @@ class TelegramPollingService {
       const senderName = [message.from?.first_name, message.from?.last_name].filter((value) => typeof value === "string" && value.trim().length > 0).join(" ").trim();
       const identity = {
         platform: "telegram",
+        accountId: this.accountId,
         conversationKind: routeInfo.conversationKind,
         senderId: message.from?.id != null ? String(message.from.id).trim() : undefined,
         senderName: senderName || message.from?.username?.trim() || undefined,
@@ -72079,7 +72807,7 @@ var telegramChannelPlugin = {
     accountId,
     config
   })),
-  createRuntimeService: (context, account) => new TelegramPollingService(context.loadedConfig, context.agentService, context.processedEventsStore, context.activityStore, account.accountId, account.config),
+  createRuntimeService: (context, account) => new TelegramPollingService(context.loadedConfig, context.agentService, context.processedEventsStore, context.activityStore, account.accountId, account.config, context.reportLifecycle),
   renderHealthSummary: (state) => {
     switch (state) {
       case "starting":
@@ -72173,7 +72901,7 @@ var defaultMessageCliDependencies = {
     await agentService.recordConversationReply(target, kind, source);
   }
 };
-function parseRepeatedOption2(args, name) {
+function parseRepeatedOption3(args, name) {
   const values = [];
   for (let index = 0;index < args.length; index += 1) {
     if (args[index] !== name) {
@@ -72188,7 +72916,7 @@ function parseRepeatedOption2(args, name) {
   return values;
 }
 function parseOptionValue4(args, name) {
-  const values = parseRepeatedOption2(args, name);
+  const values = parseRepeatedOption3(args, name);
   return values.length > 0 ? values.at(-1) : undefined;
 }
 function parseIntegerOption(args, name) {
@@ -72202,7 +72930,7 @@ function parseIntegerOption(args, name) {
   }
   return parsed;
 }
-function hasFlag3(args, name) {
+function hasFlag4(args, name) {
   return args.includes(name);
 }
 function resolveReplyKind(command) {
@@ -72234,18 +72962,18 @@ function parseMessageCommand(args) {
     media: parseOptionValue4(rest, "--media"),
     messageId: parseOptionValue4(rest, "--message-id"),
     emoji: parseOptionValue4(rest, "--emoji"),
-    remove: hasFlag3(rest, "--remove"),
+    remove: hasFlag4(rest, "--remove"),
     threadId: parseOptionValue4(rest, "--thread-id"),
     replyTo: parseOptionValue4(rest, "--reply-to"),
     limit: parseIntegerOption(rest, "--limit"),
     query: parseOptionValue4(rest, "--query"),
     pollQuestion: parseOptionValue4(rest, "--poll-question"),
-    pollOptions: parseRepeatedOption2(rest, "--poll-option"),
-    forceDocument: hasFlag3(rest, "--force-document"),
-    silent: hasFlag3(rest, "--silent"),
-    progress: hasFlag3(rest, "--progress"),
-    final: hasFlag3(rest, "--final"),
-    json: hasFlag3(rest, "--json")
+    pollOptions: parseRepeatedOption3(rest, "--poll-option"),
+    forceDocument: hasFlag4(rest, "--force-document"),
+    silent: hasFlag4(rest, "--silent"),
+    progress: hasFlag4(rest, "--progress"),
+    final: hasFlag4(rest, "--final"),
+    json: hasFlag4(rest, "--json")
   };
 }
 function renderMessageHelp() {
@@ -72468,6 +73196,7 @@ class RuntimeSupervisor {
   reloadInFlight = false;
   reloadRequested = false;
   configWatchDebounceMs = 250;
+  nextRuntimeId = 1;
   dependencies;
   constructor(configPath, dependencies) {
     this.configPath = configPath;
@@ -72484,15 +73213,50 @@ class RuntimeSupervisor {
   async start() {
     await this.reload("initial");
   }
-  async stop() {
+  async stop(options = {}) {
     this.clearReloadTimer();
     this.stopWatchingConfig();
     await this.stopActiveRuntime();
+    if (options.markChannelsStopped !== false) {
+      for (const plugin of this.dependencies.listChannelPlugins()) {
+        await this.dependencies.runtimeHealthStore.setChannel({
+          channel: plugin.id,
+          connection: "stopped",
+          summary: plugin.renderHealthSummary("stopped")
+        });
+      }
+    }
+  }
+  async markFatalFailure(error) {
+    const activeRuntime = this.activeRuntime;
+    if (!activeRuntime) {
+      return;
+    }
+    const detail = error instanceof Error ? error.message : String(error);
+    const instancesByChannel = new Map;
+    for (const entry of activeRuntime.channelServices) {
+      const identity = entry.service.getRuntimeIdentity?.();
+      if (!identity) {
+        continue;
+      }
+      const existing = instancesByChannel.get(entry.channel) ?? [];
+      existing.push(identity);
+      instancesByChannel.set(entry.channel, existing);
+    }
     for (const plugin of this.dependencies.listChannelPlugins()) {
+      if (!plugin.isEnabled(activeRuntime.loadedConfig)) {
+        continue;
+      }
       await this.dependencies.runtimeHealthStore.setChannel({
         channel: plugin.id,
-        connection: "stopped",
-        summary: plugin.renderHealthSummary("stopped")
+        connection: "failed",
+        summary: "Runtime crashed due to a fatal error.",
+        detail,
+        actions: [
+          "run `clisbot logs` and inspect the fatal error",
+          "fix the underlying runtime fault, then restart with `clisbot start`"
+        ],
+        instances: instancesByChannel.get(plugin.id) ?? []
       });
     }
   }
@@ -72570,6 +73334,7 @@ class RuntimeSupervisor {
     }
   }
   async createRuntime(loadedConfig) {
+    const runtimeId = this.nextRuntimeId++;
     const agentService = this.dependencies.createAgentService(loadedConfig);
     const processedEventsStore = this.dependencies.createProcessedEventsStore(loadedConfig.processedEventsPath);
     const activityStore = this.dependencies.createActivityStore();
@@ -72591,7 +73356,14 @@ class RuntimeSupervisor {
             loadedConfig,
             agentService,
             processedEventsStore,
-            activityStore
+            activityStore,
+            reportLifecycle: (event) => this.reportChannelLifecycle({
+              runtimeId,
+              plugin,
+              channelServices,
+              accountId: account.accountId,
+              event
+            })
           }, account)
         });
       }
@@ -72622,6 +73394,8 @@ class RuntimeSupervisor {
         });
       }
       return {
+        id: runtimeId,
+        loadedConfig,
         agentService,
         channelServices
       };
@@ -72661,6 +73435,38 @@ class RuntimeSupervisor {
       });
     }
   }
+  getChannelInstances(channelServices, channel) {
+    return channelServices.filter((entry) => entry.channel === channel).map((entry) => entry.service.getRuntimeIdentity?.()).filter((identity) => identity != null);
+  }
+  async reportChannelLifecycle(params) {
+    if (this.activeRuntime?.id !== params.runtimeId) {
+      return;
+    }
+    const instances = this.getChannelInstances(params.channelServices, params.plugin.id);
+    if (params.event.connection === "active") {
+      await this.dependencies.runtimeHealthStore.setChannel({
+        channel: params.plugin.id,
+        connection: "active",
+        summary: params.event.summary ?? params.plugin.renderActiveHealthSummary(Math.max(1, instances.length)),
+        detail: params.event.detail,
+        actions: params.event.actions,
+        instances
+      });
+      return;
+    }
+    const detailPrefix = `account=${params.accountId}`;
+    await this.dependencies.runtimeHealthStore.setChannel({
+      channel: params.plugin.id,
+      connection: "failed",
+      summary: params.event.summary ?? `${params.plugin.id} channel failed after startup.`,
+      detail: params.event.detail ? `${detailPrefix}; ${params.event.detail}` : detailPrefix,
+      actions: params.event.actions ?? [
+        "run `clisbot logs` and inspect the latest channel error",
+        "restart `clisbot` after fixing the channel-level issue"
+      ],
+      instances
+    });
+  }
   async reconcileConfigWatcher(loadedConfig) {
     const configReload = loadedConfig.raw.control.configReload;
     this.configWatchDebounceMs = configReload.watchDebounceMs;
@@ -72851,6 +73657,11 @@ async function getRuntimeOperatorSummary(params) {
   ];
   return {
     loadedConfig,
+    ownerSummary: {
+      ownerPrincipals: loadedConfig.raw.app.auth.roles.owner?.users ?? [],
+      adminPrincipals: loadedConfig.raw.app.auth.roles.admin?.users ?? [],
+      ownerClaimWindowMinutes: loadedConfig.raw.app.auth.ownerClaimWindowMinutes
+    },
     agentSummaries,
     channelSummaries,
     activeRuns: await agentService.listActiveSessionRuntimes(),
@@ -72932,11 +73743,75 @@ function renderAgentSummaryLines(summary) {
     })
   ];
 }
+function renderOwnerSummaryLines(summary) {
+  const ownerPrincipals = summary.ownerSummary.ownerPrincipals;
+  const adminPrincipals = summary.ownerSummary.adminPrincipals;
+  const configuredOwners = ownerPrincipals.length > 0 ? ownerPrincipals.join(",") : "none";
+  const claimWindow = `${summary.ownerSummary.ownerClaimWindowMinutes}m`;
+  const lines = [
+    "Owner:",
+    `  - configured=${ownerPrincipals.length > 0 ? "yes" : "no"} principals=${configuredOwners} claimWindow=${claimWindow}`,
+    "  - access=full app control, DM pairing bypass, implicit admin across all agents/channels"
+  ];
+  if (adminPrincipals.length > 0) {
+    lines.push(`  - appAdmins=${adminPrincipals.join(",")}`);
+  }
+  return lines;
+}
+function hasConfiguredPrivilegedPrincipal(summary) {
+  return summary.ownerSummary.ownerPrincipals.length > 0 || summary.ownerSummary.adminPrincipals.length > 0;
+}
+function renderPrivilegedChatHint(summary, action) {
+  if (hasConfiguredPrivilegedPrincipal(summary)) {
+    return `chat with the bot from that owner/admin account to ${action}`;
+  }
+  return `after you configure an owner/admin principal, use that account to ${action}`;
+}
+function appendChannelNextStepLines(lines, summary, prefix = "") {
+  const slackEnabled = summary.channelSummaries.some((channel) => channel.channel === "slack" && channel.enabled);
+  const telegramEnabled = summary.channelSummaries.some((channel) => channel.channel === "telegram" && channel.enabled);
+  const hasEnabledChannel = slackEnabled || telegramEnabled;
+  if (!hasEnabledChannel) {
+    lines.push(`${prefix}- run \`clisbot channels enable <slack|telegram>\` for the first channel you want to expose`);
+    return;
+  }
+  if (telegramEnabled && slackEnabled) {
+    lines.push(`${prefix}- DM the Telegram or Slack bot first to confirm it responds normally`);
+  } else if (telegramEnabled) {
+    lines.push(`${prefix}- DM the Telegram bot first to confirm it responds normally`);
+  } else {
+    lines.push(`${prefix}- DM the Slack bot first to confirm it responds normally`);
+  }
+  lines.push(`${prefix}- after DM works, add the bot to the target Slack channel or Telegram group/topic`);
+  lines.push(`${prefix}- route that surface with \`clisbot channels add slack-channel <channelId> --agent <id>\` or \`clisbot channels add telegram-group <chatId> --agent <id>\``);
+  if (telegramEnabled) {
+    lines.push(`${prefix}- Telegram: send \`/start\` in the target DM, group, or topic to get onboarding or pairing guidance`);
+  }
+  if (slackEnabled) {
+    lines.push(`${prefix}- Slack: mention \`@<botname> \\start\` in the target channel to verify mention flow`);
+  }
+}
+function appendAuthOnboardingLines(lines, summary, prefix = "") {
+  lines.push(`${prefix}Auth onboarding:`);
+  if (!hasConfiguredPrivilegedPrincipal(summary)) {
+    lines.push(`${prefix}  - get the principal from a surface the bot can already see; Telegram groups or topics can use \`/whoami\` before routing, while DMs with pairing must pair first`);
+    lines.push(`${prefix}  - set the first owner with: \`clisbot auth add-user app --role owner --user <principal>\``);
+  } else {
+    lines.push(`${prefix}  - inspect current app roles with: \`clisbot auth show app\``);
+  }
+  lines.push(`${prefix}  - inspect default agent roles with: \`clisbot auth show agent-defaults\``);
+  lines.push(`${prefix}  - add or remove principals with: \`clisbot auth add-user ...\` and \`clisbot auth remove-user ...\``);
+  lines.push(`${prefix}  - tune role permissions with: \`clisbot auth add-permission ...\` and \`clisbot auth remove-permission ...\``);
+  lines.push(`${prefix}  - run \`clisbot auth --help\` or read docs/user-guide/auth-and-roles.md for scopes and permission names`);
+}
 function renderChannelSummaryLines(summary) {
   return [
     "",
     "Channels:",
     ...summary.channelSummaries.map((channel) => {
+      if (!channel.enabled) {
+        return `  - ${channel.channel} enabled=no`;
+      }
       const last = channel.lastActivityAt ? ` last=${formatTime(channel.lastActivityAt)} via ${channel.lastActivityAgentId ?? "unknown"}` : " last=never";
       const dm = ` dm=${channel.directMessagesEnabled ? channel.directMessagesPolicy : "disabled"}`;
       const group = channel.groupPolicy ? ` groups=${channel.groupPolicy}` : "";
@@ -72992,8 +73867,9 @@ function renderRuntimeDiagnosticsSummary(summary) {
 `).trim();
 }
 function renderStartSummary(summary) {
-  const configPath = collapseHomePath(getDefaultConfigPath());
   const lines = [
+    ...renderOwnerSummaryLines(summary),
+    "",
     ...renderAgentSummaryLines(summary),
     ...renderChannelSummaryLines(summary)
   ];
@@ -73031,7 +73907,10 @@ function renderStartSummary(summary) {
     lines.push("");
     lines.push("  Next steps after bootstrap:");
     lines.push("  - chat with the bot or open the workspace, then follow BOOTSTRAP.md");
-    lines.push(`  - configure Slack channels or Telegram groups/topics in ${configPath}`);
+    appendChannelNextStepLines(lines, summary, "  ");
+    lines.push(`  - ${renderPrivilegedChatHint(summary, "verify DM access and adjust in-chat settings")}`);
+    lines.push("");
+    appendAuthOnboardingLines(lines, summary, "  ");
     lines.push("  - run `clisbot status` to recheck runtime and bootstrap state");
     lines.push("  - run `clisbot logs` if the bot does not answer as expected");
     lines.push(...renderPairingSetupHelpLines("  ", {
@@ -73049,9 +73928,11 @@ function renderStartSummary(summary) {
   }
   lines.push("");
   lines.push("Next steps:");
-  lines.push(`  - configure Slack channels or Telegram groups/topics in ${configPath}`);
-  lines.push("  - verify routing and defaultAgentId values match the agent you want to expose");
-  lines.push("  - send a test message from Slack or Telegram");
+  appendChannelNextStepLines(lines, summary, "  ");
+  lines.push("  - verify routes and defaultAgentId values match the agent you want to expose");
+  lines.push(`  - ${renderPrivilegedChatHint(summary, "adjust in-chat surface settings")}`);
+  lines.push("");
+  appendAuthOnboardingLines(lines, summary);
   lines.push("  - run `clisbot status` to inspect agents, channels, and tmux session state");
   lines.push("  - run `clisbot logs` if anything looks wrong");
   lines.push(...renderPairingSetupHelpLines("", {
@@ -73078,20 +73959,24 @@ function appendChannelSetupNotes(lines, summary, prefix = "") {
     if (channel.channel === "telegram") {
       lines.push(`${prefix}  - telegram: no explicit group or topic routes are configured yet`);
       lines.push(`${prefix}    dms: ${channel.directMessagesEnabled ? `enabled (${channel.directMessagesPolicy})` : "disabled"}`);
-      lines.push(`${prefix}    route: add channels.telegram.groups.<chatId> in ${collapseHomePath(getDefaultConfigPath())}`);
-      lines.push(`${prefix}    example: channels.telegram.groups."-1001234567890".agentId = "default"`);
-      lines.push(`${prefix}    forum topics: use channels.telegram.groups.<chatId>.topics.<topicId>`);
+      lines.push(`${prefix}    add group: \`clisbot channels add telegram-group <chatId> --agent <id>\``);
+      lines.push(`${prefix}    add topic: \`clisbot channels add telegram-group <chatId> --topic <topicId> --agent <id>\``);
+      lines.push(`${prefix}    adjust later: ${renderPrivilegedChatHint(summary, "run in-chat commands here")}`);
       continue;
     }
     lines.push(`${prefix}  - slack: no explicit channel or group routes are configured yet`);
     lines.push(`${prefix}    dms: ${channel.directMessagesEnabled ? `enabled (${channel.directMessagesPolicy})` : "disabled"}`);
     lines.push(`${prefix}    groups: ${channel.groupPolicy ?? "n/a"}`);
-    lines.push(`${prefix}    route: configure channels.slack.channels.<channelId> or channels.slack.groups.<groupId>`);
+    lines.push(`${prefix}    add channel: \`clisbot channels add slack-channel <channelId> --agent <id>\``);
+    lines.push(`${prefix}    add group: \`clisbot channels add slack-group <groupId> --agent <id>\``);
+    lines.push(`${prefix}    adjust later: ${renderPrivilegedChatHint(summary, "run in-chat commands here")}`);
   }
 }
 function renderStatusSummary(summary) {
   const lines = [
     `stats agents=${summary.configuredAgents} bootstrapped=${summary.bootstrappedAgents} pendingBootstrap=${summary.bootstrapPendingAgents} tmuxSessions=${summary.runningTmuxSessions}`,
+    ...renderOwnerSummaryLines(summary),
+    "",
     ...renderAgentSummaryLines(summary),
     ...renderChannelSummaryLines(summary),
     ...renderChannelDiagnosticLines(summary),
@@ -73113,6 +73998,15 @@ function printCommandOutcomeBanner(outcome) {
 function printCommandOutcomeFooter(outcome) {
   printCommandOutcomeBanner(outcome);
 }
+function assertSupportedPlatform(command) {
+  if (process.platform !== "win32") {
+    return;
+  }
+  if (command.name === "help" || command.name === "version") {
+    return;
+  }
+  throw new Error("Native Windows is not supported yet. Run clisbot from WSL2 or use Linux/macOS instead.");
+}
 function getPrimaryWorkspacePath(summary) {
   const preferredAgentId = summary.channelSummaries.find((channel) => channel.enabled)?.defaultAgentId ?? "default";
   return summary.agentSummaries.find((agent) => agent.id === preferredAgentId)?.workspacePath ?? summary.agentSummaries[0]?.workspacePath;
@@ -73262,25 +74156,57 @@ async function serveForeground() {
   const runtimeCredentialsPath = getDefaultRuntimeCredentialsPath();
   const runtimeSupervisor = new RuntimeSupervisor(configPath);
   let shuttingDown = false;
-  const shutdown = async (exitCode = 0) => {
+  let fatalHandling = false;
+  const shutdown = async (exitCode = 0, options = {}) => {
     if (shuttingDown) {
       return;
     }
     shuttingDown = true;
     try {
-      await runtimeSupervisor.stop();
+      await runtimeSupervisor.stop({
+        markChannelsStopped: options.markChannelsStopped
+      });
     } finally {
       removeRuntimeCredentials(runtimeCredentialsPath);
       removeRuntimePid(pidPath);
       process.exit(exitCode);
     }
   };
+  const handleFatal = async (source, error) => {
+    if (fatalHandling || shuttingDown) {
+      return;
+    }
+    fatalHandling = true;
+    const detail = error instanceof Error ? error.message : String(error);
+    const fatalError = new Error(`fatal ${source}: ${detail}`);
+    console.error(`clisbot fatal ${source}`, error);
+    const forceExitTimer = setTimeout(() => {
+      process.exit(1);
+    }, 5000);
+    forceExitTimer.unref?.();
+    try {
+      await runtimeSupervisor.markFatalFailure(fatalError);
+    } catch (markError) {
+      console.error("failed to record fatal runtime health", markError);
+    }
+    try {
+      await shutdown(1, { markChannelsStopped: false });
+    } finally {
+      clearTimeout(forceExitTimer);
+    }
+  };
   process.once("SIGINT", () => {
     shutdown(0);
   });
   process.once("SIGTERM", () => {
     shutdown(0);
   });
+  process.once("uncaughtException", (error) => {
+    handleFatal("uncaughtException", error);
+  });
+  process.once("unhandledRejection", (error) => {
+    handleFatal("unhandledRejection", error);
+  });
   try {
     await runtimeSupervisor.start();
     await writeRuntimePid(pidPath, process.pid);
@@ -73357,7 +74283,7 @@ async function start(args = []) {
       console.log(`clisbot is already running with pid: ${result.pid}`);
       const workspacePath = getPrimaryWorkspacePath(summary);
       if (workspacePath) {
-        console.log(`workspace: ${workspacePath} (agent workspace: default work dir; contains state, sessions, personality, and guidance files)`);
+        console.log(`workspace: ${workspacePath}`);
       }
       console.log(`config: ${result.configPath}`);
       console.log(`log: ${result.logPath}`);
@@ -73389,7 +74315,7 @@ async function start(args = []) {
     console.log(`clisbot started with pid: ${result.pid}`);
     const workspacePath = getPrimaryWorkspacePath(summary);
     if (workspacePath) {
-      console.log(`workspace: ${workspacePath} (agent workspace: default work dir; contains state, sessions, personality, and guidance files)`);
+      console.log(`workspace: ${workspacePath}`);
     }
     console.log(`config: ${result.configPath}`);
     console.log(`log: ${result.logPath}`);
@@ -73478,7 +74404,7 @@ async function status() {
     });
     const workspacePath = getPrimaryWorkspacePath(summary);
     if (workspacePath) {
-      console.log(`workspace: ${workspacePath} (agent workspace: default work dir; contains state, sessions, personality, and guidance files)`);
+      console.log(`workspace: ${workspacePath}`);
     }
     console.log(`config: ${runtimeStatus.configPath}`);
     console.log(`pid file: ${runtimeStatus.pidPath}`);
@@ -73521,6 +74447,7 @@ async function logs(lines) {
   } catch {}
 }
 async function main(command = parseCliArgs(process.argv)) {
+  assertSupportedPlatform(command);
   if (command.name === "help") {
     console.log(renderCliHelp());
     return;
@@ -73577,6 +74504,10 @@ async function main(command = parseCliArgs(process.argv)) {
     await runAgentsCli(command.args);
     return;
   }
+  if (command.name === "auth") {
+    await runAuthCli(command.args);
+    return;
+  }
   if (command.name === "pairing") {
     await runPairingCli(command.args);
     return;