clisbot 0.1.26 → 0.1.29

package/dist/main.js

@@ -4,43 +4,25 @@ var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-function __accessProp(key) {
-  return this[key];
-}
-var __toESMCache_node;
-var __toESMCache_esm;
 var __toESM = (mod, isNodeMode, target) => {
-  var canCache = mod != null && typeof mod === "object";
-  if (canCache) {
-    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
-    var cached = cache.get(mod);
-    if (cached)
-      return cached;
-  }
   target = mod != null ? __create(__getProtoOf(mod)) : {};
   const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
   for (let key of __getOwnPropNames(mod))
     if (!__hasOwnProp.call(to, key))
       __defProp(to, key, {
-        get: __accessProp.bind(mod, key),
+        get: () => mod[key],
         enumerable: true
       });
-  if (canCache)
-    cache.set(mod, to);
   return to;
 };
 var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
-var __returnValue = (v) => v;
-function __exportSetter(name, newValue) {
-  this[name] = __returnValue.bind(null, newValue);
-}
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
       get: all[name],
       enumerable: true,
       configurable: true,
-      set: __exportSetter.bind(all, name)
+      set: (newValue) => all[name] = () => newValue
     });
 };
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
@@ -54694,6 +54676,7 @@ function renderCliHelp() {
     "",
     "Commands:",
     `  start              Seed ${configPath} if missing, apply explicit channel-account bootstrap intent, and start clisbot in the background.`,
+    "                     See `clisbot start --help` for bootstrap-focused flags and examples.",
     "  restart            Stop the running clisbot process, then start it again.",
     "  stop               Stop the running clisbot process.",
     "  stop --hard        Stop clisbot and kill all tmux sessions on the configured clisbot socket.",
@@ -54710,20 +54693,26 @@ function renderCliHelp() {
     "                     remove slack-group <groupId>",
     "                     set-token <slack-app|slack-bot|telegram-bot> <value>",
     "                     clear-token <slack-app|slack-bot|telegram-bot>",
+    "                     See `clisbot channels --help` for route policy notes and defaults such as `requireMention`.",
     "  accounts           Manage Slack and Telegram provider accounts plus persistence state.",
     "                     add telegram --account <id> --token <ENV_NAME|${ENV_NAME}|literal> [--persist]",
     "                     add slack --account <id> --app-token <ENV_NAME|${ENV_NAME}|literal> --bot-token <ENV_NAME|${ENV_NAME}|literal> [--persist]",
     "                     persist --channel <slack|telegram> --account <id>",
     "                     persist --all",
+    "                     See `clisbot accounts --help` for env-vs-mem-vs-persist behavior.",
     "  loops              Inspect or cancel managed recurring loops persisted by `/loop`.",
     "                     list|status",
     "                     cancel <id>",
     "                     cancel --all",
+    "                     See `clisbot loops --help` for behavior notes.",
     "  message            Run provider message actions such as send, react, read, edit, delete, and pins.",
+    "                     See `clisbot message --help` for channel-specific syntax.",
     "  agents             Manage configured agents and top-level bindings.",
+    "                     See `clisbot agents --help` for focused add/bootstrap/binding help.",
     "  auth               Manage app and agent auth roles, principals, and permissions in config. See `clisbot auth --help`.",
-    "  pairing            Run the pairing control CLI.",
+    "  pairing            Run the pairing control CLI. See `clisbot pairing --help`.",
     `  init               Seed ${configPath} and optionally create the first agent without starting clisbot.`,
+    "                     See `clisbot init --help` for bootstrap-focused flags and examples.",
     "  --version, -v      Show the installed clisbot version.",
     "  --help             Show this help text.",
     "",
@@ -54766,6 +54755,35 @@ function buildPairingReply(params) {
   ].join(`
 `);
 }
+function buildPairingQueueFullReply(params) {
+  return [
+    "clisbot: access not configured.",
+    "",
+    params.idLine,
+    "",
+    "Pairing queue is full right now.",
+    "",
+    "Ask the bot owner to inspect or clear pending requests with:",
+    `clisbot pairing list ${params.channel}`,
+    `clisbot pairing reject ${params.channel} <code>`,
+    `clisbot pairing clear ${params.channel}`
+  ].join(`
+`);
+}
+function buildPairingReplyFromRequest(params) {
+  const code = params.pairingRequest.code.trim();
+  if (!code) {
+    return buildPairingQueueFullReply({
+      channel: params.channel,
+      idLine: params.idLine
+    });
+  }
+  return buildPairingReply({
+    channel: params.channel,
+    idLine: params.idLine,
+    code
+  });
+}
 function renderPairingRequests(params) {
   if (!params.requests.length) {
     return `No pending ${params.channel} pairing requests.`;
@@ -54788,7 +54806,7 @@ import path from "node:path";
 var PAIRING_CODE_LENGTH = 8;
 var PAIRING_CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
 var PAIRING_PENDING_TTL_MS = 60 * 60 * 1000;
-var PAIRING_PENDING_MAX = 3;
+var PAIRING_PENDING_MAX = 20;
 var PAIRING_STORE_LOCK_OPTIONS = {
   retries: {
     retries: 10,
@@ -55067,8 +55085,63 @@ async function approveChannelPairingCode(params) {
     return { id: entry.id, entry };
   });
 }
+async function rejectChannelPairingCode(params) {
+  const code = params.code.trim().toUpperCase();
+  if (!code) {
+    return null;
+  }
+  const filePath = resolvePairingPath(params.channel, params.baseDir);
+  return withFileLock(filePath, { version: 1, requests: [] }, async () => {
+    const { value } = await readJsonFile(filePath, {
+      version: 1,
+      requests: []
+    });
+    const requests = Array.isArray(value.requests) ? value.requests : [];
+    const { requests: pruned, removed } = pruneExpiredRequests(requests, Date.now());
+    const matchIndex = pruned.findIndex((request) => String(request.code ?? "").trim().toUpperCase() === code);
+    if (matchIndex < 0) {
+      if (removed) {
+        await writeJsonFile(filePath, {
+          version: 1,
+          requests: pruned
+        });
+      }
+      return null;
+    }
+    const [rejected] = pruned.splice(matchIndex, 1);
+    await writeJsonFile(filePath, {
+      version: 1,
+      requests: pruned
+    });
+    return rejected ?? null;
+  });
+}
+async function clearChannelPairingRequests(params) {
+  const filePath = resolvePairingPath(params.channel, params.baseDir);
+  return withFileLock(filePath, { version: 1, requests: [] }, async () => {
+    const { value } = await readJsonFile(filePath, {
+      version: 1,
+      requests: []
+    });
+    const requests = Array.isArray(value.requests) ? value.requests : [];
+    const { requests: pruned } = pruneExpiredRequests(requests, Date.now());
+    await writeJsonFile(filePath, {
+      version: 1,
+      requests: []
+    });
+    return { cleared: pruned.length };
+  });
+}
 
 // src/channels/pairing/cli.ts
+function resolvePairingBaseDir(env = process.env) {
+  const configured = env.CLISBOT_PAIRING_DIR?.trim();
+  if (configured) {
+    return configured;
+  }
+  const legacy = env.TMUX_TALK_PAIRING_DIR?.trim();
+  return legacy || undefined;
+}
 function parseChannel(raw) {
   const value = raw?.trim().toLowerCase();
   if (value === "slack" || value === "telegram") {
@@ -55076,9 +55149,33 @@ function parseChannel(raw) {
   }
   throw new Error("Channel required: slack | telegram");
 }
+function renderPairingCliHelp() {
+  return [
+    "clisbot pairing",
+    "",
+    "Usage:",
+    "  clisbot pairing --help",
+    "  clisbot pairing help",
+    "  clisbot pairing list <slack|telegram> [--json]",
+    "  clisbot pairing approve <slack|telegram> <code>",
+    "  clisbot pairing reject <slack|telegram> <code>",
+    "  clisbot pairing clear <slack|telegram>",
+    "",
+    "Notes:",
+    "  - `list` shows pending pairing requests for one channel only",
+    "  - `approve` moves that sender into the channel allowlist",
+    "  - `reject` removes one pending request without allowlisting the sender",
+    "  - `clear` drops every pending request for that channel when the queue needs a reset"
+  ].join(`
+`);
+}
 async function runPairingCli(args, writer = console) {
   const [command, ...rest] = args;
-  const baseDir = process.env.TMUX_TALK_PAIRING_DIR;
+  const baseDir = resolvePairingBaseDir();
+  if (!command || command === "--help" || command === "-h" || command === "help") {
+    writer.log(renderPairingCliHelp());
+    return;
+  }
   if (command === "list") {
     const wantsJson = rest.includes("--json");
     const channel = parseChannel(rest.find((value) => !value.startsWith("--")));
@@ -55103,7 +55200,34 @@ async function runPairingCli(args, writer = console) {
     writer.log(`Approved ${channel} sender ${approved.id}.`);
     return;
   }
-  throw new Error("Usage: pairing list <channel> [--json] | pairing approve <channel> <code>");
+  if (command === "reject") {
+    const [channelArg, code] = rest;
+    const channel = parseChannel(channelArg);
+    if (!code?.trim()) {
+      throw new Error("Usage: pairing reject <channel> <code>");
+    }
+    const rejected = await rejectChannelPairingCode({
+      channel,
+      code,
+      baseDir
+    });
+    if (!rejected) {
+      throw new Error(`No pending pairing request found for code: ${code}`);
+    }
+    writer.log(`Rejected ${channel} sender ${rejected.id}.`);
+    return;
+  }
+  if (command === "clear") {
+    const [channelArg] = rest;
+    const channel = parseChannel(channelArg);
+    const result = await clearChannelPairingRequests({
+      channel,
+      baseDir
+    });
+    writer.log(`Cleared ${result.cleared} pending ${channel} pairing request(s).`);
+    return;
+  }
+  throw new Error(renderPairingCliHelp());
 }
 
 // src/config/agent-tool-presets.ts
@@ -59283,7 +59407,7 @@ function formatConfiguredRuntimeLimit(params) {
   if (typeof params.maxRuntimeMin === "number" && Number.isFinite(params.maxRuntimeMin)) {
     return `${params.maxRuntimeMin} minute${params.maxRuntimeMin === 1 ? "" : "s"}`;
   }
-  return "15 minutes";
+  return "30 minutes";
 }
 function parseCommandDurationMs(raw) {
   const match = raw.trim().match(/^(\d+)(ms|s|m|h)$/i);
@@ -59991,7 +60115,7 @@ var agentDefaultsSchema = exports_external.object({
     updateIntervalMs: 2000,
     idleTimeoutMs: 6000,
     noOutputTimeoutMs: 20000,
-    maxRuntimeMin: 15,
+    maxRuntimeMin: 30,
     maxMessageChars: 3500
   }),
   session: sessionSchema.default({
@@ -60679,7 +60803,7 @@ function renderDefaultConfigTemplate(options = {}) {
           updateIntervalMs: 2000,
           idleTimeoutMs: 6000,
           noOutputTimeoutMs: 20000,
-          maxRuntimeMin: 15,
+          maxRuntimeMin: 30,
           maxMessageChars: 3500
         },
         session: {
@@ -61044,6 +61168,32 @@ function parseSingleOption(args, name) {
 function hasFlag(args, name) {
   return args.includes(name);
 }
+function renderAgentsHelp() {
+  return [
+    "clisbot agents",
+    "",
+    "Usage:",
+    "  clisbot agents --help",
+    "  clisbot agents help",
+    "  clisbot agents list [--bindings] [--json]",
+    "  clisbot agents add <id> --cli <codex|claude|gemini> [--workspace <path>] [--startup-option <arg>]... [--bootstrap <personal-assistant|team-assistant>] [--bind <channel[:accountId]>]...",
+    "  clisbot agents bootstrap <id> --mode <personal-assistant|team-assistant> [--force]",
+    "  clisbot agents bindings [--agent <id>] [--json]",
+    "  clisbot agents bind --agent <id> --bind <channel[:accountId]>",
+    "  clisbot agents unbind --agent <id> [--bind <channel[:accountId]> | --all]",
+    "  clisbot agents response-mode <status|set|clear> --agent <id> [capture-pane|message-tool]",
+    "  clisbot agents additional-message-mode <status|set|clear> --agent <id> [queue|steer]",
+    "",
+    "Notes:",
+    "  - `agents add` is the lower-level manual surface; first-run `clisbot start` and `clisbot init` can bootstrap the first `default` agent for you",
+    "  - `--cli` is required on `agents add`; supported tools are `codex`, `claude`, and `gemini`",
+    "  - omit `--startup-option` to inherit the built-in startup args for the selected CLI tool",
+    "  - `--bind slack`, `--bind telegram`, or `--bind <channel>:<accountId>` creates top-level fallback bindings",
+    "  - explicit route `agentId` on Slack or Telegram still wins before these fallback bindings",
+    "  - `response-mode` and `additional-message-mode` mutate per-agent overrides under `agents.list[]`"
+  ].join(`
+`);
+}
 function parseResponseMode(raw) {
   if (raw === "capture-pane" || raw === "message-tool") {
     return raw;
@@ -61373,7 +61523,11 @@ async function runAgentAdditionalMessageModeCli(args) {
 async function runAgentsCli(args) {
   const subcommand = args[0];
   const rest = args.slice(1);
-  if (!subcommand || subcommand === "list") {
+  if (!subcommand || subcommand === "--help" || subcommand === "-h" || subcommand === "help") {
+    console.log(renderAgentsHelp());
+    return;
+  }
+  if (subcommand === "list") {
     await listAgents(rest);
     return;
   }
@@ -61405,7 +61559,7 @@ async function runAgentsCli(args) {
     await unbindAgent(rest);
     return;
   }
-  throw new Error(`Unknown agents subcommand: ${subcommand}`);
+  throw new Error(renderAgentsHelp());
 }
 
 // src/control/accounts-cli.ts
@@ -63505,6 +63659,12 @@ function collapseBlankLines(lines) {
   }
   return collapsed;
 }
+var DURATION_STATUS_PATTERN = String.raw`(?:\d+(?:h|m|s))(?:\s+\d+(?:h|m|s)){0,2}`;
+var CODEX_WORKING_STATUS_PATTERN = new RegExp(String.raw`^(?:[•◦·]\s*)?Working(?:\s*\()?${DURATION_STATUS_PATTERN}\b.*(?:esc to interrupt|interrupt)\)?$`, "i");
+var CODEX_INTERRUPT_FOOTER_PATTERN = new RegExp(String.raw`^(?:[•◦·]\s*)?${DURATION_STATUS_PATTERN}\s*[•◦·]?\s*esc to interrupt\)?$`, "i");
+var GEMINI_THINKING_STATUS_PATTERN = new RegExp(String.raw`^Thinking\.\.\. \(esc to cancel,\s*${DURATION_STATUS_PATTERN}\)$`, "i");
+var CLAUDE_WORKED_STATUS_PATTERN = new RegExp(String.raw`^(?:[✻✽*]\s*)?(?:Worked|Cooked) for ${DURATION_STATUS_PATTERN}$`, "i");
+var CLAUDE_TIMER_FOOTER_PATTERN = new RegExp(String.raw`\|\s*claude\s*\|.*\|\s*${DURATION_STATUS_PATTERN}\s*$`, "i");
 function looksLikeUrlContinuation(line) {
   const trimmed = line.trim();
   return trimmed.startsWith("(") || trimmed.startsWith("http://") || trimmed.startsWith("https://");
@@ -63702,7 +63862,14 @@ function isInterruptStatusLine(line) {
   if (!trimmed) {
     return false;
   }
-  return /^(?:[•◦·]\s*)?Working(?:\s*\()?\d+s\b.*(?:esc to interrupt|interrupt)\)?$/i.test(trimmed) || /^(?:[•◦·]\s*)?\d+s\s*[•◦·]?\s*esc to interrupt\)?$/i.test(trimmed);
+  return CODEX_WORKING_STATUS_PATTERN.test(trimmed) || CODEX_INTERRUPT_FOOTER_PATTERN.test(trimmed);
+}
+function isTimerDrivenStatusLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed) {
+    return false;
+  }
+  return isInterruptStatusLine(trimmed) || GEMINI_THINKING_STATUS_PATTERN.test(trimmed) || CLAUDE_WORKED_STATUS_PATTERN.test(trimmed) || CLAUDE_TIMER_FOOTER_PATTERN.test(trimmed);
 }
 function shouldDropCodexChromeLine(line) {
   const trimmed = line.trim();
@@ -63716,14 +63883,14 @@ function shouldDropClaudeChromeLine(line) {
   if (!trimmed) {
     return false;
   }
-  return trimmed.includes("Claude Code v") || trimmed.includes("Welcome back!") || trimmed.includes("Tips for getting started") || trimmed.includes("Ask Claude to create a new app or clone a repository") || trimmed.includes("Recent activity") || trimmed.includes("No recent activity") || trimmed.includes("API Usage Billing") || trimmed.includes("shift+tab to cycle") || trimmed.includes("ctrl+o to expand") || trimmed.includes("ctrl+b ctrl+b") || trimmed.includes("run in background") || /^~\/\.clisbot\/(?:workspace\/)?[a-z0-9._/-]+$/i.test(trimmed) || trimmed.includes("| claude |") || /^(?:[✻*]\s*)?(?:Worked|Cooked) for \d+s$/i.test(trimmed) || trimmed.startsWith("⏵⏵") || trimmed.startsWith("❯") || isProgressLine(trimmed) || /^[A-Za-z0-9._-]+\.[A-Za-z0-9._-]+$/.test(trimmed) || /^[╭╰│]/.test(trimmed) || /^─+$/.test(trimmed) || /^[▐▛▜▌▝▘ ]+$/.test(trimmed) || /^[▐▛▜▌▝▘ ]+.+$/.test(trimmed);
+  return trimmed.includes("Claude Code v") || trimmed.includes("Welcome back!") || trimmed.includes("Tips for getting started") || trimmed.includes("Ask Claude to create a new app or clone a repository") || trimmed.includes("Recent activity") || trimmed.includes("No recent activity") || trimmed.includes("API Usage Billing") || trimmed.includes("shift+tab to cycle") || trimmed.includes("ctrl+o to expand") || trimmed.includes("ctrl+b ctrl+b") || trimmed.includes("run in background") || /^~\/\.clisbot\/(?:workspace\/)?[a-z0-9._/-]+$/i.test(trimmed) || trimmed.includes("| claude |") || isTimerDrivenStatusLine(trimmed) || trimmed.startsWith("⏵⏵") || trimmed.startsWith("❯") || isProgressLine(trimmed) || /^[A-Za-z0-9._-]+\.[A-Za-z0-9._-]+$/.test(trimmed) || /^[╭╰│]/.test(trimmed) || /^─+$/.test(trimmed) || /^[▐▛▜▌▝▘ ]+$/.test(trimmed) || /^[▐▛▜▌▝▘ ]+.+$/.test(trimmed);
 }
 function shouldDropGeminiChromeLine(line) {
   const trimmed = line.trim();
   if (!trimmed) {
     return false;
   }
-  return trimmed.includes("Gemini CLI v") || trimmed.includes("Signed in with Google") || trimmed.includes("Plan:") || /^[▝▜▄▗▟▀ ]+$/.test(trimmed) || trimmed.includes("We're making changes to Gemini CLI") || trimmed.includes("What's Changing:") || trimmed.includes("How it affects you:") || trimmed.includes("Read more: https://goo.gle/geminicli-updates") || trimmed.includes("Skipping project agents due to untrusted folder.") || trimmed.includes("Do you trust the files in this folder?") || trimmed.includes("Trusting a folder allows Gemini CLI to load its local configurations") || trimmed === "1. Trust folder (default)" || trimmed === "2. Trust parent folder (workspaces)" || trimmed === "3. Don't trust" || trimmed.includes("Tips for getting started") || /^Create GEMINI\.md files to customize your interactions$/i.test(trimmed) || /^\/help for more information$/i.test(trimmed) || /^Ask coding questions, edit code or run commands$/i.test(trimmed) || /^Be specific for the best results$/i.test(trimmed) || trimmed.includes("? for shortcuts") || trimmed.includes("YOLO Ctrl+Y") || trimmed.includes("Type your message or @path/to/file") || trimmed.includes("workspace (/directory)") || /^~\/.+\s+\S+\s+no sandbox\s+\S+/i.test(trimmed) || /^Thinking\.\.\. \(esc to cancel,\s*\d+s\)$/i.test(trimmed) || /^[╭╰│]/.test(trimmed) || /^[-▀▄]{10,}$/.test(trimmed) || /^─+$/.test(trimmed);
+  return trimmed.includes("Gemini CLI v") || trimmed.includes("Signed in with Google") || trimmed.includes("Plan:") || /^[▝▜▄▗▟▀ ]+$/.test(trimmed) || trimmed.includes("We're making changes to Gemini CLI") || trimmed.includes("What's Changing:") || trimmed.includes("How it affects you:") || trimmed.includes("Read more: https://goo.gle/geminicli-updates") || trimmed.includes("Skipping project agents due to untrusted folder.") || trimmed.includes("Do you trust the files in this folder?") || trimmed.includes("Trusting a folder allows Gemini CLI to load its local configurations") || trimmed === "1. Trust folder (default)" || trimmed === "2. Trust parent folder (workspaces)" || trimmed === "3. Don't trust" || trimmed.includes("Tips for getting started") || /^Create GEMINI\.md files to customize your interactions$/i.test(trimmed) || /^\/help for more information$/i.test(trimmed) || /^Ask coding questions, edit code or run commands$/i.test(trimmed) || /^Be specific for the best results$/i.test(trimmed) || trimmed.includes("? for shortcuts") || trimmed.includes("YOLO Ctrl+Y") || trimmed.includes("Type your message or @path/to/file") || trimmed.includes("workspace (/directory)") || /^~\/.+\s+\S+\s+no sandbox\s+\S+/i.test(trimmed) || isTimerDrivenStatusLine(trimmed) || /^[╭╰│]/.test(trimmed) || /^[-▀▄]{10,}$/.test(trimmed) || /^─+$/.test(trimmed);
 }
 function normalizeBoundaryLine(line) {
   return line.trim().replace(/^(?::eight_spoked_asterisk:|[-*•◦·✽✶])\s+/, "");
@@ -63757,16 +63924,21 @@ function collapseAdjacentDuplicateLines(raw) {
   return collapseBlankLines(collapsed).join(`
 `).trim();
 }
-function cleanInteractionSnapshot(raw) {
+function cleanInteractionSnapshotInternal(raw, options) {
   const lines = splitNormalizedLines(raw);
   const isCodex = looksLikeCodexSnapshot(lines);
   const isClaude = looksLikeClaudeSnapshot(lines);
   const isGemini = looksLikeGeminiSnapshot(lines);
   const promptStripped = isCodex ? dropCodexPromptBlocks(lines) : isClaude ? dropClaudePromptBlocks(lines) : isGemini ? dropGeminiPromptBlocks(lines) : lines;
+  const timerStatusLines = [];
   const filtered = promptStripped.filter((line) => {
     if (shouldDropDeliveryReportLine(line)) {
       return false;
     }
+    if (options?.preserveTimerStatusLines && isTimerDrivenStatusLine(line)) {
+      timerStatusLines.push(line.trim());
+      return false;
+    }
     if (isCodex && shouldDropCodexChromeLine(line)) {
       return false;
     }
@@ -63780,8 +63952,21 @@ function cleanInteractionSnapshot(raw) {
   });
   const normalized = isCodex ? unwrapCodexMessageBlocks(filtered) : isClaude ? unwrapClaudeMessageBlocks(filtered) : isGemini ? filtered.map((line) => line.replace(/^\s*>\s*/, "")) : filtered;
   const unwrapped = unwrapSoftWrappedLines(normalized);
-  return collapseAdjacentDuplicateLines(collapseBlankLines(trimBlankLines(unwrapped)).join(`
+  const cleanedBody = collapseAdjacentDuplicateLines(collapseBlankLines(trimBlankLines(unwrapped)).join(`
 `));
+  const cleanedTimerStatus = options?.preserveTimerStatusLines ? collapseAdjacentDuplicateLines(collapseBlankLines(trimBlankLines(timerStatusLines)).join(`
+`)) : "";
+  return [cleanedBody, cleanedTimerStatus].filter(Boolean).join(`
+
+`).trim();
+}
+function cleanInteractionSnapshot(raw) {
+  return cleanInteractionSnapshotInternal(raw);
+}
+function cleanRunningInteractionSnapshot(raw) {
+  return cleanInteractionSnapshotInternal(raw, {
+    preserveTimerStatusLines: true
+  });
 }
 // src/shared/transcript-delta.ts
 function diffText(previous, current) {
@@ -63842,16 +64027,8 @@ function extractScrolledAppend(previous, current) {
   }
   return "";
 }
-function deriveRunningInteractionText(previousSnapshot, currentSnapshot) {
-  const previous = cleanInteractionSnapshot(previousSnapshot);
-  const current = cleanInteractionSnapshot(currentSnapshot);
-  if (!current || current === previous) {
-    return "";
-  }
-  if (!previous) {
-    return current;
-  }
-  return extractScrolledAppend(previous, current);
+function deriveRunningInteractionSnapshot(currentSnapshot) {
+  return cleanRunningInteractionSnapshot(currentSnapshot);
 }
 function deriveInteractionText(initialSnapshot, currentSnapshot) {
   const previous = cleanInteractionSnapshot(initialSnapshot);
@@ -64593,6 +64770,7 @@ var TMUX_DUPLICATE_SESSION_PATTERN = /duplicate session:/i;
 var TMUX_TRANSIENT_TARGET_PATTERN = /(?:no current target|can't find pane|can't find window)/i;
 var SESSION_READY_CAPTURE_RETRY_COUNT = 5;
 var SESSION_READY_CAPTURE_RETRY_DELAY_MS = 100;
+var SESSION_ID_CAPTURE_FAILURE_COOLDOWN_MS = 15000;
 function summarizeSnapshot(snapshot) {
   const compact = snapshot.split(`
 `).map((line) => line.trim()).filter(Boolean).join(" ").slice(0, 220);
@@ -64624,6 +64802,7 @@ class RunnerService {
   sessionState;
   resolveTarget;
   cleanupInFlight = false;
+  sessionIdentityCaptureRetryAt = new Map;
   constructor(loadedConfig, tmux, sessionState, resolveTarget) {
     this.loadedConfig = loadedConfig;
     this.tmux = tmux;
@@ -64675,12 +64854,24 @@ class RunnerService {
   async syncSessionIdentity(resolved) {
     const existing = await this.sessionState.getEntry(resolved.sessionKey);
     if (existing?.sessionId) {
+      this.sessionIdentityCaptureRetryAt.delete(resolved.sessionKey);
       return this.sessionState.touchSessionEntry(resolved, {
         sessionId: existing.sessionId,
         runnerCommand: resolved.runner.command
       });
     }
+    const retryAt = this.sessionIdentityCaptureRetryAt.get(resolved.sessionKey) ?? 0;
+    if (retryAt > Date.now()) {
+      return this.sessionState.touchSessionEntry(resolved, {
+        runnerCommand: resolved.runner.command
+      });
+    }
     const sessionId = await this.captureSessionIdentity(resolved);
+    if (sessionId) {
+      this.sessionIdentityCaptureRetryAt.delete(resolved.sessionKey);
+    } else {
+      this.sessionIdentityCaptureRetryAt.set(resolved.sessionKey, Date.now() + SESSION_ID_CAPTURE_FAILURE_COOLDOWN_MS);
+    }
     return this.sessionState.touchSessionEntry(resolved, {
       sessionId,
       runnerCommand: resolved.runner.command
@@ -64835,6 +65026,7 @@ class RunnerService {
       sessionName: resolved.sessionName,
       stateDir: this.loadedConfig.stateDir
     });
+    this.sessionIdentityCaptureRetryAt.delete(resolved.sessionKey);
     try {
       await this.tmux.newSession({
         sessionName: resolved.sessionName,
@@ -65101,11 +65293,12 @@ function buildRunRecoveryNote(kind, params) {
 var FIRST_OUTPUT_POLL_INTERVAL_MS = 250;
 async function monitorTmuxRun(params) {
   let previousSnapshot = params.initialSnapshot;
-  let lastChangeAt = Date.now();
-  let sawChange = false;
-  let cumulativeInteractionSnapshot = "";
+  let previousRunningSnapshot = "";
+  let lastActivityAt = params.startedAt;
+  let sawActivity = false;
   let detachedNotified = params.detachedAlready;
   let firstMeaningfulDeltaLogged = false;
+  let noOutputThresholdLogged = false;
   if (params.prompt) {
     logLatencyDebug("tmux-submit-start", params.timingContext, {
       sessionName: params.sessionName,
@@ -65126,61 +65319,57 @@ async function monitorTmuxRun(params) {
     });
   }
   while (true) {
-    await sleep(sawChange ? params.updateIntervalMs : Math.min(params.updateIntervalMs, FIRST_OUTPUT_POLL_INTERVAL_MS));
+    await sleep(sawActivity ? params.updateIntervalMs : Math.min(params.updateIntervalMs, FIRST_OUTPUT_POLL_INTERVAL_MS));
     const snapshot = normalizePaneText(await params.tmux.capturePane(params.sessionName, params.captureLines));
     const now = Date.now();
-    if (snapshot !== previousSnapshot) {
-      const priorSnapshot = previousSnapshot;
-      lastChangeAt = now;
-      previousSnapshot = snapshot;
-      const interactionDelta = deriveRunningInteractionText(priorSnapshot, snapshot);
-      const nextInteractionSnapshot = appendInteractionText(cumulativeInteractionSnapshot, interactionDelta);
-      if (nextInteractionSnapshot && nextInteractionSnapshot !== cumulativeInteractionSnapshot) {
-        sawChange = true;
-        cumulativeInteractionSnapshot = nextInteractionSnapshot;
-        if (!firstMeaningfulDeltaLogged) {
-          firstMeaningfulDeltaLogged = true;
-          logLatencyDebug("tmux-first-meaningful-delta", params.timingContext, {
-            sessionName: params.sessionName,
-            elapsedMs: now - params.startedAt
-          });
-        }
-        await params.onRunning({
-          snapshot: cumulativeInteractionSnapshot,
-          fullSnapshot: snapshot,
-          initialSnapshot: params.initialSnapshot
+    const runningSnapshot = deriveRunningInteractionSnapshot(snapshot);
+    previousSnapshot = snapshot;
+    if (runningSnapshot && runningSnapshot !== previousRunningSnapshot) {
+      previousRunningSnapshot = runningSnapshot;
+      lastActivityAt = now;
+      sawActivity = true;
+      if (!firstMeaningfulDeltaLogged) {
+        firstMeaningfulDeltaLogged = true;
+        logLatencyDebug("tmux-first-meaningful-delta", params.timingContext, {
+          sessionName: params.sessionName,
+          elapsedMs: now - params.startedAt
         });
       }
+      await params.onRunning({
+        snapshot: runningSnapshot,
+        fullSnapshot: snapshot,
+        initialSnapshot: params.initialSnapshot
+      });
     }
     if (!detachedNotified && now - params.startedAt >= params.maxRuntimeMs) {
       detachedNotified = true;
       await params.onDetached({
-        snapshot: cumulativeInteractionSnapshot || deriveInteractionText(params.initialSnapshot, previousSnapshot),
+        snapshot: previousRunningSnapshot || deriveInteractionText(params.initialSnapshot, snapshot),
         fullSnapshot: previousSnapshot,
         initialSnapshot: params.initialSnapshot
       });
     }
-    if (sawChange && now - lastChangeAt >= params.idleTimeoutMs) {
+    if (sawActivity && now - lastActivityAt >= params.idleTimeoutMs) {
       await params.onCompleted({
-        snapshot: cumulativeInteractionSnapshot || deriveInteractionText(params.initialSnapshot, previousSnapshot),
+        snapshot: deriveInteractionText(params.initialSnapshot, previousSnapshot),
         fullSnapshot: previousSnapshot,
         initialSnapshot: params.initialSnapshot
       });
       return;
     }
-    if (!sawChange && now - params.startedAt >= params.noOutputTimeoutMs) {
-      await params.onTimeout({
-        snapshot: cumulativeInteractionSnapshot || deriveInteractionText(params.initialSnapshot, previousSnapshot),
-        fullSnapshot: previousSnapshot,
-        initialSnapshot: params.initialSnapshot
+    if (!noOutputThresholdLogged && !sawActivity && now - params.startedAt >= params.noOutputTimeoutMs) {
+      noOutputThresholdLogged = true;
+      logLatencyDebug("tmux-no-output-threshold-crossed", params.timingContext, {
+        sessionName: params.sessionName,
+        elapsedMs: now - params.startedAt
       });
-      return;
     }
   }
 }
 
 // src/agents/session-service.ts
 var OBSERVER_RETRYABLE_FAILURE_LIMIT = 3;
+var DETACHED_OBSERVER_INTERVAL_MS = 5 * 60000;
 function formatObserverError(error) {
   return error instanceof Error ? error.stack ?? error.message : String(error);
 }
@@ -65428,7 +65617,10 @@ class SessionService {
         detached: false
       };
     }
-    observer.mode = "passive-final";
+    observer.mode = "poll";
+    observer.intervalMs = DETACHED_OBSERVER_INTERVAL_MS;
+    observer.expiresAt = undefined;
+    observer.lastSentAt = Date.now();
     run.observerFailures.delete(observerId);
     return {
       detached: true
@@ -65451,7 +65643,19 @@ class SessionService {
     this.activeRuns.clear();
   }
   buildDetachedNote(resolved) {
-    return `This session has been running for over ${resolved.stream.maxRuntimeLabel}. clisbot will keep monitoring it and will post the final result here when it completes. Use \`/attach\` to resume live updates, \`/watch every 30s\` for interval updates, or \`/stop\` to interrupt it.`;
+    return `This session has been running for over ${resolved.stream.maxRuntimeLabel}. clisbot will keep monitoring it, switch this thread to sparse progress updates, and post the final result here when it completes. Use \`/attach\` to resume live updates, \`/watch every 30s\` for interval updates, or \`/stop\` to interrupt it.`;
+  }
+  applyDetachedObserverPolicy(run) {
+    const now = Date.now();
+    for (const observer of run.observers.values()) {
+      if (observer.mode !== "live") {
+        continue;
+      }
+      observer.mode = "poll";
+      observer.intervalMs = DETACHED_OBSERVER_INTERVAL_MS;
+      observer.expiresAt = undefined;
+      observer.lastSentAt = now;
+    }
   }
   createRunUpdate(params) {
     return {
@@ -65682,7 +65886,8 @@ class SessionService {
               startedAt: params.startedAt,
               detachedAt: Date.now()
             });
-            currentRun.latestUpdate = detachedUpdate;
+            await this.notifyRunObservers(currentRun, detachedUpdate);
+            this.applyDetachedObserverPolicy(currentRun);
             currentRun.initialResult.resolve(detachedUpdate);
           },
           onCompleted: async (update) => {
@@ -65694,16 +65899,6 @@ class SessionService {
               initialSnapshot: update.initialSnapshot
             });
             await this.finishActiveRun(sessionKey, runUpdate);
-          },
-          onTimeout: async (update) => {
-            const runUpdate = this.createRunUpdate({
-              resolved: run.resolved,
-              status: "timeout",
-              snapshot: mergeRunSnapshot(params.snapshotPrefix ?? "", update.snapshot),
-              fullSnapshot: update.fullSnapshot,
-              initialSnapshot: update.initialSnapshot
-            });
-            await this.finishActiveRun(sessionKey, runUpdate);
           }
         });
       } catch (error) {
@@ -65720,6 +65915,28 @@ class SessionService {
 }
 
 // src/agents/agent-service.ts
+function shellQuote3(value) {
+  if (/^[a-zA-Z0-9_./:@=-]+$/.test(value)) {
+    return value;
+  }
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+function buildCommandString2(command, args) {
+  return [command, ...args].map(shellQuote3).join(" ");
+}
+function stripWorkspaceArgs(args) {
+  const filtered = [];
+  for (let index = 0;index < args.length; index += 1) {
+    const current = args[index];
+    if (current === "-C") {
+      index += 1;
+      continue;
+    }
+    filtered.push(current);
+  }
+  return filtered;
+}
+
 class AgentService {
   loadedConfig;
   tmuxClient;
@@ -65810,6 +66027,15 @@ class AgentService {
   async getSessionRuntime(target) {
     return this.sessionState.getSessionRuntime(target);
   }
+  async getSessionDiagnostics(target) {
+    const resolved = this.resolveTarget(target);
+    const entry = await this.sessionState.getEntry(target.sessionKey);
+    const sessionId = entry?.sessionId?.trim() || undefined;
+    return {
+      sessionId,
+      resumeCommand: this.buildResumeCommandPreview(resolved, sessionId)
+    };
+  }
   async listActiveSessionRuntimes() {
     return this.sessionState.listActiveSessionRuntimes();
   }
@@ -66052,6 +66278,21 @@ class AgentService {
       this.scheduleIntervalLoopTimer(persisted.id, Math.max(0, persisted.nextRunAt - Date.now()));
     }
   }
+  buildResumeCommandPreview(resolved, sessionId) {
+    if (!sessionId || resolved.runner.sessionId.resume.mode !== "command") {
+      return;
+    }
+    const values = {
+      agentId: resolved.agentId,
+      workspace: resolved.workspacePath,
+      sessionName: resolved.sessionName,
+      sessionKey: resolved.sessionKey,
+      sessionId
+    };
+    const command = resolved.runner.sessionId.resume.command ?? resolved.runner.command;
+    const args = stripWorkspaceArgs(resolved.runner.sessionId.resume.args.map((value) => applyTemplate(value, values)));
+    return buildCommandString2(command, args);
+  }
   async isManagedLoopPersisted(managed) {
     const entry = await this.sessionState.getEntry(managed.target.sessionKey);
     return (entry?.intervalLoops ?? []).some((loop) => loop.id === managed.loop.id);
@@ -66556,6 +66797,12 @@ function parseAgentCommand(text, options = {}) {
   if (lowered === "loop") {
     const loopText = withoutSlash.slice(command.length).trim();
     const loweredLoopText = loopText.toLowerCase();
+    if (!loweredLoopText || loweredLoopText === "help") {
+      return {
+        type: "control",
+        name: "loop-help"
+      };
+    }
     if (loweredLoopText === "status") {
       return {
         type: "loop-control",
@@ -66603,6 +66850,12 @@ function parseAgentCommand(text, options = {}) {
     const queueText = withoutSlash.slice(command.length).trim();
     const normalizedQueueText = queueText.toLowerCase();
     if (lowered === "queue") {
+      if (normalizedQueueText === "help") {
+        return {
+          type: "control",
+          name: "queue-help"
+        };
+      }
       if (normalizedQueueText === "list") {
         return {
           type: "control",
@@ -66669,7 +66922,7 @@ function renderAgentControlSlashHelp() {
     "- `/whoami`: show the current platform, route, and sender identity details",
     "- `/transcript`: show the current conversation session transcript when the route verbose policy allows it",
     "- `/attach`: attach this thread to the active run and resume live updates when it is still processing",
-    "- `/detach`: stop live updates for this thread while still allowing final settlement here",
+    "- `/detach`: stop live updates for this thread, switch to sparse progress updates, and still allow final settlement here",
     "- `/watch every 30s [for 10m]`: post the latest state on an interval until the run settles or the watch window ends",
     "- `/stop`: send Escape to interrupt the current conversation session",
     "- `/nudge`: send one extra Enter to the current tmux session without resending the prompt text",
@@ -66686,9 +66939,11 @@ function renderAgentControlSlashHelp() {
     "- `/additionalmessagemode steer`: send later user messages straight into the active session",
     "- `/additionalmessagemode queue`: queue later user messages behind the active run for this surface",
     "- `/queue <message>` or `\\q <message>`: enqueue a later message behind the active run and let clisbot deliver it in order",
+    "- `/queue help`: show queue-specific help and examples",
     "- `/steer <message>` or `\\s <message>`: inject a steering message into the active run immediately",
     "- `/queue list`: show queued messages that have not started yet",
     "- `/queue clear`: clear queued messages that have not started yet",
+    "- `/loop help`: show loop-specific help and syntax examples",
     ...renderLoopHelpLines(),
     "- `/bash` followed by a shell command: requires `shellExecute` on the resolved agent role",
     "- shortcut prefixes such as `!` run bash only when the resolved agent role allows `shellExecute`",
@@ -66697,6 +66952,15 @@ function renderAgentControlSlashHelp() {
   ].join(`
 `);
 }
+function renderQueueHelpLines() {
+  return [
+    "- `/queue <message>` or `\\q <message>`: enqueue one later message behind the active run",
+    "- `/queue list`: show queued messages that have not started yet",
+    "- `/queue clear`: clear queued messages that have not started yet",
+    "- `/queue help`: show this queue help again",
+    "- `/steer <message>` or `\\s <message>`: inject an immediate steering message instead of queueing"
+  ];
+}
 function parseWatchCommand(raw) {
   const match = raw.match(/^every\s+(\S+)(?:\s+for\s+(\S+))?$/i);
   if (!match) {
@@ -66918,7 +67182,8 @@ function renderWhoAmIMessage(params) {
     `platform: \`${params.identity.platform}\``,
     `conversationKind: \`${params.identity.conversationKind}\``,
     `agentId: \`${params.route.agentId}\``,
-    `sessionKey: \`${params.sessionTarget.sessionKey}\``
+    `sessionKey: \`${params.sessionTarget.sessionKey}\``,
+    `storedSessionId: \`${params.sessionDiagnostics.sessionId ?? "(not captured yet)"}\``
   ];
   if (params.identity.senderId) {
     lines.push(`senderId: \`${params.identity.senderId}\``);
@@ -66935,7 +67200,7 @@ function renderWhoAmIMessage(params) {
   if (params.identity.topicId) {
     lines.push(`topicId: \`${params.identity.topicId}\``);
   }
-  lines.push(`principal: \`${params.auth.principal ?? "(none)"}\``, `principalFormat: \`${renderPrincipalFormat(params.identity)}\``, `principalExample: \`${renderPrincipalExample(params.identity)}\``, `appRole: \`${params.auth.appRole}\``, `agentRole: \`${params.auth.agentRole}\``, `mayBypassPairing: \`${params.auth.mayBypassPairing}\``, `mayManageProtectedResources: \`${params.auth.mayManageProtectedResources}\``, `canUseShell: \`${params.auth.canUseShell}\``, `verbose: \`${params.route.verbose}\``);
+  lines.push(`resumeCommand: \`${params.sessionDiagnostics.resumeCommand ?? "(not available yet)"}\``, `principal: \`${params.auth.principal ?? "(none)"}\``, `principalFormat: \`${renderPrincipalFormat(params.identity)}\``, `principalExample: \`${renderPrincipalExample(params.identity)}\``, `appRole: \`${params.auth.appRole}\``, `agentRole: \`${params.auth.agentRole}\``, `mayBypassPairing: \`${params.auth.mayBypassPairing}\``, `mayManageProtectedResources: \`${params.auth.mayManageProtectedResources}\``, `canUseShell: \`${params.auth.canUseShell}\``, `verbose: \`${params.route.verbose}\``);
   return lines.join(`
 `);
 }
@@ -66946,7 +67211,8 @@ function renderRouteStatusMessage(params) {
     `platform: \`${params.identity.platform}\``,
     `conversationKind: \`${params.identity.conversationKind}\``,
     `agentId: \`${params.route.agentId}\``,
-    `sessionKey: \`${params.sessionTarget.sessionKey}\``
+    `sessionKey: \`${params.sessionTarget.sessionKey}\``,
+    `storedSessionId: \`${params.sessionDiagnostics.sessionId ?? "(not captured yet)"}\``
   ];
   if (params.identity.senderId) {
     lines.push(`senderId: \`${params.identity.senderId}\``);
@@ -66963,7 +67229,7 @@ function renderRouteStatusMessage(params) {
   if (params.identity.topicId) {
     lines.push(`topicId: \`${params.identity.topicId}\``);
   }
-  lines.push(`principal: \`${params.auth.principal ?? "(none)"}\``, `principalFormat: \`${renderPrincipalFormat(params.identity)}\``, `principalExample: \`${renderPrincipalExample(params.identity)}\``, `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}\``, `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(`resumeCommand: \`${params.sessionDiagnostics.resumeCommand ?? "(not available yet)"}\``, `principal: \`${params.auth.principal ?? "(none)"}\``, `principalFormat: \`${renderPrincipalFormat(params.identity)}\``, `principalExample: \`${renderPrincipalExample(params.identity)}\``, `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}\``, `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()}\``);
   }
@@ -66977,7 +67243,7 @@ function renderRouteStatusMessage(params) {
       lines.push(`- \`${loop.id}\` ${renderLoopStatusSchedule(loop)} remaining \`${loop.remainingRuns}\` nextRunAt \`${new Date(loop.nextRunAt).toISOString()}\``);
     }
   }
-  lines.push("", "Useful commands:", "- `/help`", "- `/whoami`", "- `/status`", "- `/attach`, `/detach`, `/watch every 30s`", "- `/followup status`", "- `/streaming status|on|off|latest|all`", "- `/responsemode status`", "- `/additionalmessagemode status`", "- `/loop status`, `/loop cancel`, `/loop cancel <id>`", "- `/queue <message>`, `/steer <message>`", "- `/queue list`, `/queue clear`", params.route.verbose === "off" ? "- `/transcript` disabled on this route (`verbose: off`)" : "- `/transcript` enabled on this route (`verbose: minimal`)", "- `/bash` requires `shellExecute`");
+  lines.push("", "Useful commands:", "- `/help`", "- `/whoami`", "- `/status`", "- `/attach`, `/detach`, `/watch every 30s`", "- `/followup status`", "- `/streaming status|on|off|latest|all`", "- `/responsemode status`", "- `/additionalmessagemode status`", "- `/loop help`, `/loop status`, `/loop cancel`, `/loop cancel <id>`", "- `/queue help`, `/queue <message>`, `/steer <message>`", "- `/queue list`, `/queue clear`", params.route.verbose === "off" ? "- `/transcript` disabled on this route (`verbose: off`)" : "- `/transcript` enabled on this route (`verbose: minimal`)", "- `/bash` requires `shellExecute`");
   return lines.join(`
 `);
 }
@@ -67049,9 +67315,22 @@ function renderQueuedMessagesList(items) {
   return lines.join(`
 `).trimEnd();
 }
+function renderQueueUsage() {
+  return [
+    "Queue commands",
+    "",
+    ...renderQueueHelpLines(),
+    "",
+    "Notes:",
+    "- use queue when the current run should finish first and the next user request can wait in order",
+    "- use steer when the active run should be nudged or redirected immediately"
+  ].join(`
+`);
+}
 function renderLoopUsage() {
   return [
     "Usage:",
+    "- `/loop help`",
     "- `/loop 5m check CI`",
     "- `/loop 1m --force check CI`",
     "- `/loop 5m`",
@@ -67602,6 +67881,7 @@ async function processChannelInteraction(params) {
   };
   let replyRecorded = false;
   let renderChain = Promise.resolve();
+  const sessionDiagnostics = await params.agentService.getSessionDiagnostics?.(params.sessionTarget) ?? {};
   async function recordReplyIfNeeded() {
     if (replyRecorded) {
       return;
@@ -67676,6 +67956,7 @@ async function processChannelInteraction(params) {
         route: params.route,
         auth,
         sessionTarget: params.sessionTarget,
+        sessionDiagnostics,
         followUpState,
         runtimeState,
         loopState: {
@@ -67696,7 +67977,8 @@ async function processChannelInteraction(params) {
         identity: params.identity,
         route: params.route,
         auth,
-        sessionTarget: params.sessionTarget
+        sessionTarget: params.sessionTarget,
+        sessionDiagnostics
       }));
       await params.agentService.recordConversationReply(params.sessionTarget);
       return interactionResult;
@@ -67853,6 +68135,11 @@ async function processChannelInteraction(params) {
       await params.agentService.recordConversationReply(params.sessionTarget);
       return interactionResult;
     }
+    if (slashCommand.name === "queue-help") {
+      await params.postText(renderQueueUsage());
+      await params.agentService.recordConversationReply(params.sessionTarget);
+      return interactionResult;
+    }
     if (slashCommand.name === "queue-clear") {
       const clearedCount = params.agentService.clearQueuedPrompts?.(params.sessionTarget) ?? 0;
       await params.postText(clearedCount > 0 ? `Cleared ${clearedCount} queued message${clearedCount === 1 ? "" : "s"}.` : "Queue was already empty.");
@@ -67860,6 +68147,11 @@ async function processChannelInteraction(params) {
       return interactionResult;
     }
   }
+  if (slashCommand?.type === "control" && slashCommand.name === "loop-help") {
+    await params.postText(renderLoopUsage());
+    await params.agentService.recordConversationReply(params.sessionTarget);
+    return interactionResult;
+  }
   if (slashCommand?.type === "loop-control") {
     if (slashCommand.action === "status") {
       await params.postText(renderLoopStatusMessage({
@@ -68686,7 +68978,7 @@ async function clearSlackAssistantThreadStatus(client, target) {
 
 // src/channels/processing-indicator.ts
 function shouldResolveIndicatorWait(update) {
-  return isTerminalRunStatus(update.status) || update.status === "detached";
+  return isTerminalRunStatus(update.status);
 }
 async function waitForProcessingIndicatorLifecycle(params) {
   if (params.lifecycle !== "active-run") {
@@ -68817,6 +69109,7 @@ class ConversationProcessingIndicatorCoordinator {
 }
 
 // src/channels/slack/processing-decoration.ts
+var DEFAULT_STATUS_REFRESH_INTERVAL_MS = 2000;
 async function activateSlackProcessingDecoration(params) {
   const [reactionResult, statusResult] = await Promise.allSettled([
     params.addReaction(),
@@ -68838,7 +69131,38 @@ async function activateSlackProcessingDecoration(params) {
       throw statusResult.reason;
     }
   }
+  let statusRefreshTimer;
+  let closed = false;
+  let refreshInFlight = false;
+  let refreshPromise;
+  if (statusApplied) {
+    const refreshIntervalMs = Math.max(0, params.statusRefreshIntervalMs ?? DEFAULT_STATUS_REFRESH_INTERVAL_MS);
+    if (refreshIntervalMs > 0) {
+      statusRefreshTimer = setInterval(() => {
+        if (closed || refreshInFlight) {
+          return;
+        }
+        refreshInFlight = true;
+        refreshPromise = params.setStatus().then(() => {
+          return;
+        }).catch((error) => {
+          if (!closed) {
+            params.onUnexpectedError?.("refresh-status", error);
+          }
+        }).finally(() => {
+          refreshInFlight = false;
+          refreshPromise = undefined;
+        });
+      }, refreshIntervalMs);
+    }
+  }
   return async () => {
+    closed = true;
+    if (statusRefreshTimer) {
+      clearInterval(statusRefreshTimer);
+      statusRefreshTimer = undefined;
+    }
+    await refreshPromise;
     if (reactionApplied) {
       try {
         await params.removeReaction();
@@ -69736,20 +70060,21 @@ class SlackSocketService {
         });
         if (!allowed) {
           if (dmConfig.policy === "pairing") {
-            const { code, created } = await upsertChannelPairingRequest({
+            const pairingRequest = await upsertChannelPairingRequest({
               channel: "slack",
               id: directUserId
             });
-            if (created && code) {
+            const pairingReply = buildPairingReplyFromRequest({
+              channel: "slack",
+              idLine: `Your Slack user id: ${directUserId}`,
+              pairingRequest
+            });
+            if (pairingReply) {
               try {
                 await postSlackText(this.app.client, {
                   channel: channelId,
                   threadTs: directReplyThreadTs,
-                  text: buildPairingReply({
-                    channel: "slack",
-                    idLine: `Your Slack user id: ${directUserId}`,
-                    code
-                  })
+                  text: pairingReply
                 });
               } catch (error) {
                 console.error("slack pairing reply failed", error);
@@ -71344,7 +71669,7 @@ class TelegramPollingService {
         });
         if (!allowed) {
           if (directMessages.policy === "pairing") {
-            const { code, created } = await upsertChannelPairingRequest({
+            const pairingRequest = await upsertChannelPairingRequest({
               channel: "telegram",
               id: senderId,
               meta: {
@@ -71353,15 +71678,16 @@ class TelegramPollingService {
                 lastName: message.from?.last_name
               }
             });
-            if (created && code) {
+            const pairingReply = buildPairingReplyFromRequest({
+              channel: "telegram",
+              idLine: `Your Telegram user id: ${senderId}`,
+              pairingRequest
+            });
+            if (pairingReply) {
               try {
                 await callTelegramApi(this.accountConfig.botToken, "sendMessage", {
                   chat_id: message.chat.id,
-                  text: buildPairingReply({
-                    channel: "telegram",
-                    idLine: `Your Telegram user id: ${senderId}`,
-                    code
-                  })
+                  text: pairingReply
                 });
               } catch (error) {
                 console.error("telegram pairing reply failed", error);
@@ -73035,10 +73361,17 @@ function renderAccountsHelp() {
     "",
     "Usage:",
     "  clisbot accounts --help",
+    "  clisbot accounts help",
     "  clisbot accounts add telegram --account <id> --token <ENV_NAME|${ENV_NAME}|literal> [--persist]",
     "  clisbot accounts add slack --account <id> --app-token <ENV_NAME|${ENV_NAME}|literal> --bot-token <ENV_NAME|${ENV_NAME}|literal> [--persist]",
     "  clisbot accounts persist --channel <slack|telegram> --account <id>",
-    "  clisbot accounts persist --all"
+    "  clisbot accounts persist --all",
+    "",
+    "Notes:",
+    "  - env-style input such as `TELEGRAM_BOT_TOKEN` or `${TELEGRAM_BOT_TOKEN}` keeps the account env-backed in config",
+    "  - literal token input without `--persist` stays runtime-only and requires a running clisbot runtime",
+    "  - `--persist` writes canonical token files so later plain `clisbot start` can reuse the account safely",
+    "  - `persist --all` converts every configured `credentialType=mem` account into canonical token files"
   ].join(`
 `);
 }
@@ -73215,7 +73548,7 @@ async function runAccountsCli(args, deps = {}) {
     ...deps
   };
   const action = args[0];
-  if (!action || action === "--help" || action === "-h") {
+  if (!action || action === "--help" || action === "-h" || action === "help") {
     console.log(renderAccountsHelp());
     return;
   }
@@ -73319,6 +73652,7 @@ function renderAuthCliHelp() {
     "  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",
+    "  app `owner` and `admin` principals bypass DM pairing automatically once they are granted",
     "",
     "Examples:",
     "  clisbot auth add-user app --role owner --user telegram:1276408333",
@@ -73581,6 +73915,7 @@ function renderChannelsHelp() {
     "  - Slack private groups need channels.slack.groups.<groupId>",
     "  - Telegram groups need channels.telegram.groups.<chatId>",
     "  - Telegram forum topics need channels.telegram.groups.<chatId>.topics.<topicId>",
+    "  - route adds for Slack channels, Slack groups, Telegram groups, and Telegram topics default to `requireMention: true` unless you pass `--require-mention false`",
     "  - Adding a route puts that surface on the allowlist; other channels, groups, or topics still need to be added explicitly",
     "  - Tune route settings such as requireMention and followUp in clisbot.json when a surface should behave differently",
     `  - Manage routed auth and /bash access in ${AUTH_USER_GUIDE_DOC_PATH}`,
@@ -73659,6 +73994,7 @@ function renderRouteAddGuidance(params) {
     console.log(`  - route added: ${routePath}`);
     console.log("  - direct messages still follow channels.slack.directMessages.policy (`open`, `pairing`, `allowlist`, or `disabled`)");
     console.log(`  - this ${routeLabel} still follows channels.slack.groupPolicy and route settings such as requireMention and followUp`);
+    console.log("  - new Slack channel/group routes default to `requireMention: true` unless you passed `--require-mention false`");
     console.log("  - if you want pairing-style access control for DMs, set channels.slack.directMessages.policy to `pairing`");
     console.log("  - if you want stricter route access, keep Slack groups on allowlist and only add the channels/groups you trust");
     console.log(`  - manage routed auth and /bash access in ${AUTH_USER_GUIDE_DOC_PATH}`);
@@ -73669,6 +74005,7 @@ function renderRouteAddGuidance(params) {
     console.log(`  - route added: ${routePath}`);
     console.log("  - direct messages still follow channels.telegram.directMessages.policy (`open`, `pairing`, `allowlist`, or `disabled`)");
     console.log(`  - this ${params.kind} is now on the Telegram allowlist; other groups or topics still need to be added explicitly`);
+    console.log("  - new Telegram group/topic routes default to `requireMention: true` unless you passed `--require-mention false`");
     console.log("  - if you want pairing-style access control for DMs, set channels.telegram.directMessages.policy to `pairing`");
     console.log("  - tune route settings such as requireMention and followUp in clisbot.json if this surface should behave differently");
     console.log(`  - manage routed auth and /bash access in ${AUTH_USER_GUIDE_DOC_PATH}`);
@@ -73867,7 +74204,7 @@ async function addSlackRoute(kind, args) {
   }
   const { config, configPath } = await readEditableConfig(getEditableConfigPath7());
   const agentId = getAgentId(args);
-  const requireMention = parseBooleanOption(args, "--require-mention", false);
+  const requireMention = parseBooleanOption(args, "--require-mention", true);
   const target = kind === "channel" ? config.channels.slack.channels : config.channels.slack.groups;
   target[routeId] = {
     ...target[routeId] ?? {},
@@ -75098,6 +75435,41 @@ function assertSupportedPlatform(command) {
 }
 
 // src/control/runtime-bootstrap-cli.ts
+function hasHelpFlag(args) {
+  return args.includes("--help") || args.includes("-h") || args.includes("help");
+}
+function renderBootstrapCommandHelp(commandName) {
+  const behavior = commandName === "start" ? "seed config if needed and start the detached runtime" : "seed config and optionally bootstrap the first agent without starting runtime";
+  return [
+    `clisbot ${commandName}`,
+    "",
+    "Usage:",
+    `  clisbot ${commandName} --help`,
+    `  clisbot ${commandName} [--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>]...",
+    "                   [--telegram-account <id> --telegram-bot-token <ENV_NAME|${ENV_NAME}|literal>]...",
+    "",
+    "Behavior:",
+    `  - ${behavior}`,
+    "  - first-run agent bootstrap needs both `--cli` and `--bot-type`",
+    "  - `--bot-type personal` maps to `personal-assistant`; `--bot-type team` maps to `team-assistant`",
+    "  - explicit credential flags only enable the channels and accounts you named in this command",
+    "  - env-style values such as `SLACK_APP_TOKEN` or `${SLACK_APP_TOKEN}` stay env-backed in config",
+    commandName === "start" ? "  - literal token values without `--persist` stay runtime-only for this start invocation" : "  - literal token values on `init` require `--persist` because no runtime exists yet",
+    "  - `--persist` writes canonical credential files so later plain `clisbot start` can reuse them",
+    "",
+    "Examples:",
+    `  clisbot ${commandName} --cli codex --bot-type personal --telegram-bot-token TELEGRAM_BOT_TOKEN`,
+    `  clisbot ${commandName} --cli codex --bot-type team --slack-app-token SLACK_APP_TOKEN --slack-bot-token SLACK_BOT_TOKEN`,
+    `  clisbot ${commandName} --cli gemini --bot-type personal --telegram-bot-token "$TELEGRAM_BOT_TOKEN" --persist`,
+    "",
+    "Related help:",
+    "  - `clisbot agents --help` for lower-level agent bootstrap and binding control",
+    "  - `clisbot accounts --help` for account persistence after first run",
+    "  - `clisbot channels --help` for route setup after bootstrap"
+  ].join(`
+`);
+}
 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;
@@ -75314,6 +75686,10 @@ async function printStartedRuntimeSummary(pid, configPath, logPath) {
   }
 }
 async function initConfig(args = []) {
+  if (hasHelpFlag(args)) {
+    console.log(renderBootstrapCommandHelp("init"));
+    return;
+  }
   const state = await prepareBootstrapState(args, "init");
   if (!state) {
     return;
@@ -75332,6 +75708,10 @@ async function initConfig(args = []) {
   }
 }
 async function start(args = []) {
+  if (hasHelpFlag(args)) {
+    console.log(renderBootstrapCommandHelp("start"));
+    return;
+  }
   const runtimeStatus = await getRuntimeStatus();
   const bootstrapFlags = parseBootstrapFlags(args);
   const restartForLiteralBootstrap = runtimeStatus.running && hasLiteralMemCredentials(bootstrapFlags);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clisbot",
-  "version": "0.1.26",
+  "version": "0.1.29",
   "private": false,
   "description": "Chat surfaces for durable AI coding agents running in tmux",
   "license": "MIT",

package/templates/slack/default/app-manifest-guide.md

@@ -90,7 +90,7 @@ These are broad or legacy-looking for the current `clisbot` Slack design and sho
 | `function_executed` event | Not consumed by current code |
 | `app_home.messages_tab_enabled` and related App Home surface config | Not required for current chat-routing behavior |
 | `org_deploy_enabled` | Not needed for the current local or workspace-level setup story |
-| `hermes_app_type` and `function_runtime` | Not needed for the current Slack Socket Mode bot |
+| `function_runtime` | Not needed for the current Slack Socket Mode bot |
 
 ## Practical Recommendation
 

package/templates/slack/default/app-manifest.json

@@ -51,7 +51,6 @@
         },
         "org_deploy_enabled": false,
         "socket_mode_enabled": true,
-        "token_rotation_enabled": false,
-        "hermes_app_type": "remote"
+        "token_rotation_enabled": false
     }
 }