clisbot 0.1.45-beta.4 → 0.1.45-beta.5

package/README.md

@@ -118,7 +118,7 @@ If you want to try first without persisting the token yet, just remove `--persis
 Next steps:
 
 - For security, DMs default to pairing.
-- Existing `0.1.43` configs upgrade directly to `0.1.45` automatically on first run. clisbot writes a backup first under `~/.clisbot/backups/`, then rewrites the config to the current shape.
+- Existing configs from any version before `0.1.45` update directly to `0.1.45` automatically on first run. clisbot writes a backup first under `~/.clisbot/backups/`, then rewrites the config to the current shape.
 - Shared Slack channels, Slack groups, Telegram groups, and Telegram topics are a separate gate: normal users need an explicit route such as `group:<id>` or `topic:<chatId>:<topicId>` before the bot will talk there. Legacy Slack `channel:<id>` input still works for compatibility.
 - After a shared surface is admitted, per-surface sender control comes from the bot's default shared rule `groups["*"]` plus any route-local `allowUsers` or `blockUsers`.
 - If the effective shared policy is `disabled`, the bot stays silent there for everyone, including owner/admin.
@@ -139,7 +139,7 @@ Need the step-by-step setup docs instead of the shortest path?
 
 - Telegram: [Telegram Bot Setup](docs/user-guide/telegram-setup.md)
 - Slack: [Slack App Setup](docs/user-guide/slack-setup.md)
-- Release notes: [CHANGELOG.md](CHANGELOG.md) and [docs/releases/](docs/releases/README.md)
+- Release history: [CHANGELOG.md](CHANGELOG.md), [release notes](docs/releases/README.md), [update guide](docs/update/README.md), [operator updates](docs/updates/README.md), and [migration index](docs/migrations/index.md)
 - Slack app manifest template: [app-manifest.json](templates/slack/default/app-manifest.json)
 - Slack app manifest guide: [app-manifest-guide.md](templates/slack/default/app-manifest-guide.md)
 
@@ -152,18 +152,20 @@ What happens next:
 - fresh bootstrap only enables the channels you name explicitly
 - after the persisted first run, later restarts can use plain `clisbot start`
 
-## Big Upgrades In v0.1.39
+## Recent Release Highlights
 
-- Much better native Slack and Telegram rendering, so replies are easier to read and feel far less like pasted terminal output.
-- A much cleaner first-run path, with a clearer bot-first setup story and better setup docs.
-- Stronger pairing, auth, and safer shared-channel behavior by default.
-- More trustworthy long-running work, with better attach, detach, recovery, and operator visibility.
-- Real recurring automation with `/loop`.
+- `v0.1.45`: safer personal and team bots in real Slack and Telegram groups, automatic direct updates from older installs, more reliable scheduled loops, clearer sender and surface context, Telegram audio support, and stricter streaming/session isolation.
+- `v0.1.43`: more durable runtime recovery, clearer routed follow-up controls, more truthful tmux prompt submission checks, better queued-start notifications, and safer Slack thread attachment behavior.
+- `v0.1.39`: the first large release of the current bot-first shape, with native Slack and Telegram rendering, cleaner first-run setup, stronger pairing/auth defaults, better long-running run visibility, and recurring `/loop` automation.
+
+There are many more useful fixes and operator improvements in the full release notes, including config update safety, CLI help, setup docs, runner debugging, route policy behavior, and channel-specific polish.
 
 Read the full notes here:
 
 - [CHANGELOG.md](CHANGELOG.md)
 - [Release Notes Index](docs/releases/README.md)
+- [v0.1.45 Release Notes](docs/releases/v0.1.45.md)
+- [v0.1.43 Release Notes](docs/releases/v0.1.43.md)
 - [v0.1.39 Release Notes](docs/releases/v0.1.39.md)
 
 If you prefer Slack first:
@@ -191,11 +193,11 @@ bun run start --cli codex --bot-type personal --telegram-bot-token <your-telegra
 
 Repo-local `bun run start|stop|restart|status|logs|init|pairing` is pinned by `.env` to `CLISBOT_HOME=~/.clisbot-dev`, so local testing does not accidentally reuse your main `~/.clisbot` runtime.
 
-Upgrade note for existing installs:
+Update note for existing installs:
 
 - `v0.1.39` includes breaking changes in config shape and in the main CLI command surface.
-- If you already run an older install, ask Codex or Claude in this repo to update your current config before upgrading.
-- The upgrade itself is still simple:
+- If you already run an older install, ask Codex or Claude in this repo to update your current config before updating the package.
+- The package update itself is still simple:
 
 ```bash
 clisbot stop
@@ -337,7 +339,7 @@ Most users only need a small set of commands at first:
 
 - `clisbot start`: start the bot runtime and create the default first-run setup when needed.
 - `clisbot restart`: restart the runtime cleanly; use this first when the bot stops responding.
-- `clisbot stop`: stop the runtime cleanly before upgrades, config changes, or maintenance.
+- `clisbot stop`: stop the runtime cleanly before updates, config changes, or maintenance.
 - `clisbot stop --hard`: stop the runtime and kill all tmux runner sessions on the configured clisbot socket; use this when stale runner panes, old environment variables, or stuck sessions survive a normal restart.
 - `clisbot status`: check whether the runtime, channels, and active sessions look healthy.
 - `clisbot logs`: inspect recent runtime logs when startup, routing, or replies look wrong.

package/config/clisbot.json.template

@@ -324,7 +324,6 @@
             "socketPath": "~/.clisbot-dev/state/clisbot.sock"
           },
           "trustWorkspace": true,
-          "startupDelayMs": 3000,
           "startupRetryCount": 2,
           "startupRetryDelayMs": 1000,
           "promptSubmitDelayMs": 150,

package/dist/main.js

@@ -54634,6 +54634,12 @@ function parseCliArgs(argv) {
       lines: parseLineCount(args.slice(1))
     };
   }
+  if (command === "update") {
+    return {
+      name: "update",
+      args: args.slice(1)
+    };
+  }
   if (command === "timezone") {
     return {
       name: "timezone",
@@ -54757,6 +54763,7 @@ function renderCliHelp() {
     `  ${renderCliCommand("status")}`,
     `  ${renderCliCommand("version")}`,
     `  ${renderCliCommand("logs [--lines N]")}`,
+    `  ${renderCliCommand("update --help")}`,
     `  ${renderCliCommand("timezone <get|set|clear|doctor>")}`,
     `  ${renderCliCommand("bots <subcommand>")}`,
     `  ${renderCliCommand("routes <subcommand>")}`,
@@ -54781,6 +54788,8 @@ function renderCliHelp() {
     "  status             Show runtime process, config, log, tmux socket status, and recent runner sessions.",
     "  version            Show the installed clisbot version.",
     "  logs               Print the most recent clisbot log lines.",
+    "  update             Print the AI-readable package update guide and release/migration doc links.",
+    `                     See ${renderCliCommand("update --help", { inline: true })} before asking an agent to update clisbot.`,
     "  timezone           Manage the app-wide wall-clock timezone used by schedules and loops.",
     `                     See ${renderCliCommand("timezone --help", { inline: true })} for override guidance.`,
     "  bots               Manage provider bot identities, credentials, and bot-level fallback settings.",
@@ -59304,6 +59313,7 @@ function convertLocalDateTimeToUtcMs(params) {
 var SUPPORTED_AGENT_CLI_TOOLS = ["codex", "claude", "gemini"];
 var SUPPORTED_BOOTSTRAP_MODES = ["personal-assistant", "team-assistant"];
 var SESSION_ID_PATTERN = "\\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\\b";
+var INTERACTIVE_CLI_STARTUP_DELAY_MS = 15000;
 var DEFAULT_AGENT_TOOL_TEMPLATES = {
   codex: {
     command: "codex",
@@ -59312,7 +59322,7 @@ var DEFAULT_AGENT_TOOL_TEMPLATES = {
       "--no-alt-screen"
     ],
     trustWorkspace: true,
-    startupDelayMs: 3000,
+    startupDelayMs: INTERACTIVE_CLI_STARTUP_DELAY_MS,
     startupRetryCount: 2,
     startupRetryDelayMs: 1000,
     startupReadyPattern: "(?:^|\\s)›\\s",
@@ -59346,7 +59356,7 @@ var DEFAULT_AGENT_TOOL_TEMPLATES = {
     command: "claude",
     startupOptions: ["--dangerously-skip-permissions"],
     trustWorkspace: true,
-    startupDelayMs: 3000,
+    startupDelayMs: INTERACTIVE_CLI_STARTUP_DELAY_MS,
     startupRetryCount: 2,
     startupRetryDelayMs: 1000,
     promptSubmitDelayMs: 150,
@@ -59376,7 +59386,7 @@ var DEFAULT_AGENT_TOOL_TEMPLATES = {
     command: "gemini",
     startupOptions: ["--approval-mode=yolo", "--sandbox=false"],
     trustWorkspace: true,
-    startupDelayMs: 15000,
+    startupDelayMs: INTERACTIVE_CLI_STARTUP_DELAY_MS,
     startupRetryCount: 2,
     startupRetryDelayMs: 1000,
     startupReadyPattern: "Type your message or @path/to/file",
@@ -61287,6 +61297,7 @@ var agentsDefaultsSchema = exports_external.object({
         "-C",
         "{workspace}"
       ],
+      startupDelayMs: INTERACTIVE_CLI_STARTUP_DELAY_MS,
       startupReadyPattern: codexStartupReadyPattern,
       sessionId: {
         create: {
@@ -61316,6 +61327,7 @@ var agentsDefaultsSchema = exports_external.object({
     claude: runnerFamilySchema.default({
       command: "claude",
       args: ["--dangerously-skip-permissions"],
+      startupDelayMs: INTERACTIVE_CLI_STARTUP_DELAY_MS,
       sessionId: {
         create: {
           mode: "explicit",
@@ -61337,7 +61349,7 @@ var agentsDefaultsSchema = exports_external.object({
     gemini: runnerFamilySchema.default({
       command: "gemini",
       args: ["--approval-mode=yolo", "--sandbox=false"],
-      startupDelayMs: 15000,
+      startupDelayMs: INTERACTIVE_CLI_STARTUP_DELAY_MS,
       startupRetryCount: 2,
       startupRetryDelayMs: 1000,
       startupReadyPattern: "Type your message or @path/to/file",
@@ -61737,6 +61749,7 @@ var clisbotConfigSchema = exports_external.object({
             "-C",
             "{workspace}"
           ],
+          startupDelayMs: INTERACTIVE_CLI_STARTUP_DELAY_MS,
           startupReadyPattern: codexStartupReadyPattern,
           sessionId: {
             create: {
@@ -61766,6 +61779,7 @@ var clisbotConfigSchema = exports_external.object({
         claude: {
           command: "claude",
           args: ["--dangerously-skip-permissions"],
+          startupDelayMs: INTERACTIVE_CLI_STARTUP_DELAY_MS,
           sessionId: {
             create: {
               mode: "explicit",
@@ -61787,7 +61801,7 @@ var clisbotConfigSchema = exports_external.object({
         gemini: {
           command: "gemini",
           args: ["--approval-mode=yolo", "--sandbox=false"],
-          startupDelayMs: 15000,
+          startupDelayMs: INTERACTIVE_CLI_STARTUP_DELAY_MS,
           startupRetryCount: 2,
           startupRetryDelayMs: 1000,
           startupReadyPattern: "Type your message or @path/to/file",
@@ -61864,6 +61878,7 @@ var clisbotConfigSchema = exports_external.object({
             "-C",
             "{workspace}"
           ],
+          startupDelayMs: INTERACTIVE_CLI_STARTUP_DELAY_MS,
           startupReadyPattern: codexStartupReadyPattern,
           sessionId: {
             create: {
@@ -61893,6 +61908,7 @@ var clisbotConfigSchema = exports_external.object({
         claude: {
           command: "claude",
           args: ["--dangerously-skip-permissions"],
+          startupDelayMs: INTERACTIVE_CLI_STARTUP_DELAY_MS,
           sessionId: {
             create: {
               mode: "explicit",
@@ -61914,7 +61930,7 @@ var clisbotConfigSchema = exports_external.object({
         gemini: {
           command: "gemini",
           args: ["--approval-mode=yolo", "--sandbox=false"],
-          startupDelayMs: 15000,
+          startupDelayMs: INTERACTIVE_CLI_STARTUP_DELAY_MS,
           startupRetryCount: 2,
           startupRetryDelayMs: 1000,
           startupReadyPattern: "Type your message or @path/to/file",
@@ -62028,6 +62044,9 @@ var defaultOwnedRunnerFields = {
     "promptSubmitDelayMs"
   ]
 };
+var defaultOwnedRunnerDefaultFields = {
+  startupDelayMs: 3000
+};
 function isRecord5(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -62092,6 +62111,14 @@ function pruneRunnerDefaults(config, forceRunnerStartupDefaults) {
   if (!runner) {
     return;
   }
+  const runnerDefaults = runner.defaults;
+  if (isRecord5(runnerDefaults)) {
+    for (const [field, defaultValue] of Object.entries(defaultOwnedRunnerDefaultFields)) {
+      if (forceRunnerStartupDefaults || Object.hasOwn(runnerDefaults, field) && areJsonEqual(runnerDefaults[field], defaultValue)) {
+        delete runnerDefaults[field];
+      }
+    }
+  }
   for (const toolId of ["codex", "gemini"]) {
     const target = runner[toolId];
     if (isRecord5(target)) {
@@ -62136,20 +62163,49 @@ function pruneConfigForPersistence(config, options = {}) {
 }
 
 // src/config/config-upgrade.ts
-function readSchemaVersion(value) {
+function isRecord6(value) {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    return;
+    return false;
   }
-  const meta = value.meta;
-  if (typeof meta !== "object" || meta === null || Array.isArray(meta)) {
+  return true;
+}
+function readSchemaVersion(value) {
+  if (!isRecord6(value) || !isRecord6(value.meta)) {
     return;
   }
-  const schemaVersion = meta.schemaVersion;
+  const schemaVersion = value.meta.schemaVersion;
   return typeof schemaVersion === "string" ? schemaVersion.trim() : undefined;
 }
+function readMetaRecord(value) {
+  return isRecord6(value) && isRecord6(value.meta) ? value.meta : {};
+}
 function logUpgradeStage(message) {
   console.warn(`clisbot config upgrade: ${message}`);
 }
+function stableConfigText(config) {
+  return `${JSON.stringify(config, null, 2)}
+`;
+}
+function pruneCurrentSchemaStartupDefaults(config) {
+  const nextConfig = structuredClone(config);
+  const meta = readMetaRecord(nextConfig);
+  if (readSchemaVersion(nextConfig) !== CURRENT_SCHEMA_VERSION) {
+    return nextConfig;
+  }
+  const agents = isRecord6(nextConfig.agents) ? nextConfig.agents : undefined;
+  const defaults = isRecord6(agents?.defaults) ? agents.defaults : undefined;
+  const runner = isRecord6(defaults?.runner) ? defaults.runner : undefined;
+  const runnerDefaults = isRecord6(runner?.defaults) ? runner.defaults : undefined;
+  if (runnerDefaults?.startupDelayMs === 3000) {
+    delete runnerDefaults.startupDelayMs;
+    nextConfig.meta = {
+      ...meta,
+      schemaVersion: CURRENT_SCHEMA_VERSION,
+      lastTouchedAt: new Date().toISOString()
+    };
+  }
+  return nextConfig;
+}
 function renderBackupTimestamp(date = new Date) {
   return date.toISOString().replaceAll(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
 }
@@ -62172,6 +62228,23 @@ async function upgradeEditableConfigFileIfNeeded(configPath) {
   const rawConfig = JSON.parse(originalText);
   const fromVersion = readSchemaVersion(rawConfig);
   if (!shouldUpgradeConfigSchema(fromVersion)) {
+    const persistedConfig2 = pruneCurrentSchemaStartupDefaults(rawConfig);
+    if (stableConfigText(persistedConfig2) !== stableConfigText(rawConfig)) {
+      const backupPath2 = await reserveBackupPath(expandedConfigPath, fromVersion);
+      await writeTextFile(backupPath2, originalText.endsWith(`
+`) ? originalText : `${originalText}
+`);
+      const normalizedDocument2 = normalizeConfigDocumentShape(persistedConfig2);
+      assertNoLegacyPrivilegeCommands(normalizedDocument2);
+      clisbotConfigSchema.parse(applyDynamicPathDefaults(normalizedDocument2));
+      await writeTextFile(expandedConfigPath, stableConfigText(persistedConfig2));
+      return {
+        upgraded: false,
+        pruned: true,
+        backupPath: backupPath2,
+        schemaVersion: fromVersion || CURRENT_SCHEMA_VERSION
+      };
+    }
     return { upgraded: false };
   }
   const versionLabel = fromVersion || "legacy";
@@ -62191,14 +62264,13 @@ async function upgradeEditableConfigFileIfNeeded(configPath) {
   const persistedConfig = pruneConfigForPersistence(normalizedConfig, {
     forceRunnerStartupDefaults: true
   });
-  await writeTextFile(expandedConfigPath, `${JSON.stringify({
+  await writeTextFile(expandedConfigPath, stableConfigText({
     ...persistedConfig,
     meta: {
       ...normalizedConfig.meta,
       lastTouchedAt: new Date().toISOString()
     }
-  }, null, 2)}
-`);
+  }));
   logUpgradeStage(`applied ${versionLabel} -> ${CURRENT_SCHEMA_VERSION}; backup: ${collapseHomePath(backupPath)}`);
   return {
     upgraded: true,
@@ -62459,7 +62531,6 @@ function renderDefaultConfigTemplate(options = {}) {
               socketPath: tmuxSocketPath
             },
             trustWorkspace: true,
-            startupDelayMs: 3000,
             startupRetryCount: 2,
             startupRetryDelayMs: 1000,
             promptSubmitDelayMs: 150,
@@ -65667,6 +65738,12 @@ function parseAgentCommand(text, options = {}) {
       name: "stop"
     };
   }
+  if (lowered === "new") {
+    return {
+      type: "control",
+      name: "new"
+    };
+  }
   if (lowered === "nudge") {
     return {
       type: "control",
@@ -65902,6 +65979,7 @@ function renderAgentControlSlashHelp() {
     "- `/detach`: stop live updates for this thread while still posting the final result 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",
+    "- `/new`: trigger a new runner conversation for this routed session and store the new session id",
     "- `/nudge`: send one extra Enter to the current tmux session without resending the prompt text",
     "- `/followup status`: show the current conversation follow-up policy",
     "- `/followup auto`: allow natural follow-up after the bot has replied in-thread",
@@ -67075,7 +67153,7 @@ function buildReplyStyleHint(identity) {
 function renderConfigurationGuidance() {
   const cliName = getRenderedCliName();
   return [
-    `When the user asks to change ${cliName} configuration, use ${cliName} CLI commands; see ${renderCliCommand("--help", { inline: true })}, ${renderCliCommand("bots --help", { inline: true })}, ${renderCliCommand("routes --help", { inline: true })}, or ${renderCliCommand("auth --help", { inline: true })} for details.`,
+    `When the user asks to change ${cliName} configuration, use ${cliName} CLI commands; see ${renderCliCommand("--help", { inline: true })}, ${renderCliCommand("bots --help", { inline: true })}, ${renderCliCommand("routes --help", { inline: true })}, ${renderCliCommand("auth --help", { inline: true })}, or ${renderCliCommand("update --help", { inline: true })} for details.`,
     `For schedule/loop/reminder requests, inspect ${renderCliCommand("loops --help", { inline: true })} and use the loops CLI.`
   ].join(`
 `);
@@ -68092,6 +68170,16 @@ function isTimerDrivenStatusLine(line) {
 function hasActiveTimerStatus(snapshot) {
   return splitNormalizedLines(snapshot).some((line) => isActiveTimerStatusLine(line));
 }
+function extractLatestActiveTimerStatusLine(snapshot) {
+  const lines = splitNormalizedLines(snapshot);
+  for (let index = lines.length - 1;index >= 0; index -= 1) {
+    const line = lines[index]?.trim() ?? "";
+    if (isActiveTimerStatusLine(line)) {
+      return line;
+    }
+  }
+  return "";
+}
 function shouldDropCodexChromeLine(line) {
   const trimmed = line.trim();
   if (!trimmed) {
@@ -68274,7 +68362,11 @@ function getPromptMarker(lines) {
   }
   return null;
 }
-function sliceFromLastPromptBlock(raw) {
+function slicePromptBlockFrom(lines, index) {
+  return lines.slice(index).join(`
+`);
+}
+function sliceFromLastPromptBlock(raw, cleanSnapshot) {
   const lines = splitNormalizedLines(raw);
   const marker = getPromptMarker(lines);
   if (!marker) {
@@ -68284,17 +68376,19 @@ function sliceFromLastPromptBlock(raw) {
     if (!marker.test((lines[index] ?? "").trimStart())) {
       continue;
     }
-    return lines.slice(index).join(`
-`);
+    const promptTail = slicePromptBlockFrom(lines, index);
+    if (cleanSnapshot(promptTail)) {
+      return promptTail;
+    }
   }
   return "";
 }
 function deriveLatestPromptInteractionSnapshot(currentSnapshot) {
-  const promptTail = sliceFromLastPromptBlock(currentSnapshot);
+  const promptTail = sliceFromLastPromptBlock(currentSnapshot, cleanInteractionSnapshot);
   return promptTail ? cleanInteractionSnapshot(promptTail) : "";
 }
 function deriveLatestPromptRunningInteractionSnapshot(currentSnapshot) {
-  const promptTail = sliceFromLastPromptBlock(currentSnapshot);
+  const promptTail = sliceFromLastPromptBlock(currentSnapshot, cleanRunningInteractionSnapshot);
   return promptTail ? cleanRunningInteractionSnapshot(promptTail) : "";
 }
 function deriveInteractionText(initialSnapshot, currentSnapshot) {
@@ -68849,7 +68943,7 @@ async function captureTmuxSessionIdentity(params) {
       });
       continue;
     }
-    const sessionId = extractSessionId(deriveInteractionText(statusSubmission.submittedSnapshot, snapshot), params.pattern);
+    const sessionId = extractSessionId(deriveSessionIdentityText(statusSubmission.submittedSnapshot, snapshot), params.pattern);
     if (sessionId) {
       await waitForTmuxPaneSettle({
         tmux: params.tmux,
@@ -68864,6 +68958,11 @@ async function captureTmuxSessionIdentity(params) {
   }
   return null;
 }
+function deriveSessionIdentityText(submittedSnapshot, snapshot) {
+  const rawSubmitted = normalizePaneText(submittedSnapshot);
+  const rawSnapshot = normalizePaneText(snapshot);
+  return extractScrolledAppend(rawSubmitted, rawSnapshot) || deriveInteractionText(submittedSnapshot, snapshot);
+}
 async function dismissTmuxTrustPromptIfPresent(params) {
   const deadline = Date.now() + Math.max(TRUST_PROMPT_MAX_WAIT_MS, params.startupDelayMs);
   while (Date.now() <= deadline) {
@@ -69344,6 +69443,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|no such pane|no such window|tmux pane state unavailable)/i;
 var SESSION_READY_CAPTURE_RETRY_COUNT = 5;
 var SESSION_READY_CAPTURE_RETRY_DELAY_MS = 100;
+var TRIGGER_NEW_SESSION_CAPTURE_RETRY_COUNT = 3;
 var SESSION_ID_CAPTURE_FAILURE_COOLDOWN_MS = 15000;
 function summarizeSnapshot(snapshot) {
   const compact = snapshot.split(`
@@ -69465,9 +69565,9 @@ class RunnerService {
       runnerCommand: resolved.runner.command
     });
   }
-  async captureSessionIdentity(resolved) {
+  async captureSessionIdentity(resolved, options = {}) {
     const capture = resolved.runner.sessionId.capture;
-    if (capture.mode !== "status-command") {
+    if (capture.mode !== "status-command" && !options.forceStatusCommand) {
       return null;
     }
     return captureTmuxSessionIdentity({
@@ -69481,14 +69581,11 @@ class RunnerService {
       pollIntervalMs: capture.pollIntervalMs
     });
   }
-  async retryFreshStartWithClearedSessionId(target, resolved, remainingFreshRetries) {
+  async retryRunnerRestartPreservingSessionId(target, resolved, remainingFreshRetries) {
     if (remainingFreshRetries <= 0) {
       return null;
     }
-    await this.tmux.killSession(resolved.sessionName);
-    await this.sessionState.clearSessionIdEntry(resolved, {
-      runnerCommand: resolved.runner.command
-    });
+    await this.killRunnerAndPreserveSessionId(resolved);
     if (resolved.runner.startupRetryDelayMs > 0) {
       await sleep(resolved.runner.startupRetryDelayMs);
     }
@@ -69500,10 +69597,10 @@ class RunnerService {
     if (!isRetryableFreshStartFault(error)) {
       return null;
     }
-    return this.retryFreshStartWithClearedSessionId(target, resolved, remainingFreshRetries);
+    return this.retryRunnerRestartPreservingSessionId(target, resolved, remainingFreshRetries);
   }
   async retryAfterStartupTimeout(target, resolved, remainingFreshRetries) {
-    return this.retryFreshStartWithClearedSessionId(target, resolved, remainingFreshRetries);
+    return this.retryRunnerRestartPreservingSessionId(target, resolved, remainingFreshRetries);
   }
   resolveRemainingFreshRetries(resolved, options) {
     if (typeof options.remainingFreshRetries === "number") {
@@ -69728,7 +69825,7 @@ class RunnerService {
       if (options.allowFreshRetryBeforePrompt === false || !isRecoverableStartupSessionLoss(error)) {
         throw await this.mapSessionError(error, resolved.sessionName, "before prompt submission", resolved.sessionName ? await this.captureSessionSnapshot(resolved).catch(() => "") : "");
       }
-      const retried = await this.retryFreshStartWithClearedSessionId(target, resolved, resolved.runner.startupRetryCount);
+      const retried = await this.retryRunnerRestartPreservingSessionId(target, resolved, resolved.runner.startupRetryCount);
       if (!retried) {
         throw await this.mapSessionError(error, resolved.sessionName, "before prompt submission", resolved.sessionName ? await this.captureSessionSnapshot(resolved).catch(() => "") : "");
       }
@@ -69753,17 +69850,116 @@ class RunnerService {
     }
     return this.ensureRunnerReady(target, { allowFreshRetryBeforePrompt: false, timingContext });
   }
-  async startFreshSession(target, timingContext) {
+  async restartRunnerWithFreshSessionId(target, timingContext) {
     const resolved = this.resolveTarget(target);
     await this.tmux.killSession(resolved.sessionName).catch(() => {
       return;
     });
+    console.log(`clisbot clearing stored sessionId for explicit fresh session ${resolved.sessionName}`);
     await this.sessionState.clearSessionIdEntry(resolved, { runnerCommand: resolved.runner.command });
     return this.ensureRunnerReady(target, {
       allowFreshRetryBeforePrompt: false,
       timingContext
     });
   }
+  async triggerNewSession(target) {
+    const resolved = this.resolveTarget(target);
+    if (!await this.tmux.hasSession(resolved.sessionName)) {
+      return this.restartRunnerWithFreshSessionIdForNewCommand(target);
+    }
+    return this.triggerNewSessionInLiveRunner(resolved);
+  }
+  async restartRunnerPreservingSessionId(target, timingContext) {
+    const resolved = this.resolveTarget(target);
+    await this.killRunnerAndPreserveSessionId(resolved);
+    return this.ensureRunnerReady(target, {
+      allowFreshRetryBeforePrompt: false,
+      timingContext
+    });
+  }
+  async triggerNewSessionInLiveRunner(resolved) {
+    const oldSessionId = (await this.sessionState.getEntry(resolved.sessionKey))?.sessionId;
+    const command = this.resolveNewSessionCommand(resolved);
+    let sessionId = null;
+    for (let attempt = 0;attempt < 2; attempt += 1) {
+      await this.submitNewSessionCommand(resolved, command);
+      sessionId = await this.captureNewSessionIdentityAfterTrigger(resolved, oldSessionId);
+      if (sessionId) {
+        break;
+      }
+    }
+    if (!sessionId) {
+      await this.clearSessionIdAfterNewSessionFailure(resolved, command);
+    }
+    await this.sessionState.touchSessionEntry(resolved, {
+      sessionId,
+      runnerCommand: resolved.runner.command,
+      runtime: {
+        state: "idle"
+      }
+    });
+    return {
+      agentId: resolved.agentId,
+      sessionKey: resolved.sessionKey,
+      sessionName: resolved.sessionName,
+      workspacePath: resolved.workspacePath,
+      command,
+      sessionId,
+      restartedRunner: false
+    };
+  }
+  async restartRunnerWithFreshSessionIdForNewCommand(target) {
+    const { resolved } = await this.restartRunnerWithFreshSessionId(target);
+    const entry = await this.sessionState.getEntry(resolved.sessionKey);
+    return {
+      agentId: resolved.agentId,
+      sessionKey: resolved.sessionKey,
+      sessionName: resolved.sessionName,
+      workspacePath: resolved.workspacePath,
+      command: "(fresh runner)",
+      sessionId: entry?.sessionId,
+      restartedRunner: true
+    };
+  }
+  async submitNewSessionCommand(resolved, command) {
+    await submitTmuxSessionInput({
+      tmux: this.tmux,
+      sessionName: resolved.sessionName,
+      text: command,
+      promptSubmitDelayMs: resolved.runner.promptSubmitDelayMs,
+      timingContext: undefined
+    });
+  }
+  async captureNewSessionIdentityAfterTrigger(resolved, oldSessionId) {
+    for (let attempt = 0;attempt < TRIGGER_NEW_SESSION_CAPTURE_RETRY_COUNT; attempt += 1) {
+      const sessionId = await this.captureSessionIdentity(resolved, {
+        forceStatusCommand: true
+      });
+      if (sessionId && sessionId !== oldSessionId) {
+        return sessionId;
+      }
+      if (attempt < TRIGGER_NEW_SESSION_CAPTURE_RETRY_COUNT - 1) {
+        await sleep(SESSION_READY_CAPTURE_RETRY_DELAY_MS);
+      }
+    }
+    return null;
+  }
+  async clearSessionIdAfterNewSessionFailure(resolved, command) {
+    console.log(`clisbot clearing stored sessionId after ${command} because status capture returned no id for ${resolved.sessionName}`);
+    await this.sessionState.clearSessionIdEntry(resolved, {
+      runnerCommand: resolved.runner.command
+    });
+    throw new Error(`${command} completed, but clisbot could not capture a new session id from the runner status command.`);
+  }
+  async killRunnerAndPreserveSessionId(resolved) {
+    await this.tmux.killSession(resolved.sessionName);
+    await this.sessionState.touchSessionEntry(resolved, {
+      runnerCommand: resolved.runner.command
+    });
+  }
+  resolveNewSessionCommand(resolved) {
+    return resolved.runner.command.toLowerCase().includes("gemini") ? "/clear" : "/new";
+  }
   async captureTranscript(target) {
     const resolved = this.resolveTarget(target);
     if (!await this.tmux.hasSession(resolved.sessionName)) {
@@ -69897,6 +70093,12 @@ function buildRunRecoveryNote(kind, params) {
   if (kind === "fresh-attempt") {
     return "The previous runner session could not be resumed. Opening a fresh runner session 2/2 without replaying your prompt.";
   }
+  if (kind === "resume-failed") {
+    return "The previous runner session could not be resumed. The stored session id was preserved; use `/new` to intentionally trigger a new runner conversation.";
+  }
+  if (kind === "manual-new-required") {
+    return "The previous runner session could not be resumed. clisbot preserved the stored session id instead of opening a new conversation automatically. Use `/new` if you want to trigger a new runner conversation, then resend the prompt.";
+  }
   return "The previous runner session could not be resumed. clisbot opened a new fresh session, but did not replay your prompt because the prior conversation context is no longer guaranteed. Please resend the full prompt/context to continue.";
 }
 
@@ -69907,6 +70109,17 @@ function shouldUsePostSubmitBaseline(snapshot, prompt) {
   const trimmedPrompt = prompt.trim();
   return Boolean(trimmedPrompt) && snapshot.includes(trimmedPrompt);
 }
+function appendLatestActiveTimer(snapshot, fullSnapshot) {
+  const timerStatus = extractLatestActiveTimerStatusLine(fullSnapshot);
+  if (!timerStatus) {
+    return snapshot;
+  }
+  const body = splitNormalizedLines(snapshot).filter((line) => !isActiveTimerStatusLine(line)).join(`
+`).trim();
+  return [body, timerStatus].filter(Boolean).join(`
+
+`);
+}
 async function monitorTmuxRun(params) {
   let baselineSnapshot = params.initialSnapshot;
   let previousSnapshot = params.initialSnapshot;
@@ -69966,10 +70179,11 @@ async function monitorTmuxRun(params) {
       snapshot: nextRunningTruth,
       maxLines: RUNNING_REWRITE_PREVIEW_MAX_LINES
     }) : "";
+    const renderedRunningSnapshot = appendLatestActiveTimer(runningSnapshot, snapshot);
     previousSnapshot = snapshot;
     previousRunningTruth = nextRunningTruth;
-    if (runningSnapshot && runningSnapshot !== previousRenderedRunningSnapshot) {
-      previousRenderedRunningSnapshot = runningSnapshot;
+    if (renderedRunningSnapshot && renderedRunningSnapshot !== previousRenderedRunningSnapshot) {
+      previousRenderedRunningSnapshot = renderedRunningSnapshot;
       sawActivity = true;
       if (!firstMeaningfulDeltaLogged) {
         firstMeaningfulDeltaLogged = true;
@@ -69979,7 +70193,7 @@ async function monitorTmuxRun(params) {
         });
       }
       await params.onRunning({
-        snapshot: runningSnapshot,
+        snapshot: renderedRunningSnapshot,
         fullSnapshot: snapshot,
         initialSnapshot: baselineSnapshot
       });
@@ -70069,11 +70283,15 @@ class ActiveRunInProgressError extends Error {
 function createDeferred() {
   let resolve;
   let reject;
+  const promise = new Promise((nextResolve, nextReject) => {
+    resolve = nextResolve;
+    reject = nextReject;
+  });
+  promise.catch(() => {
+    return;
+  });
   const deferred = {
-    promise: new Promise((nextResolve, nextReject) => {
-      resolve = nextResolve;
-      reject = nextReject;
-    }),
+    promise,
     resolve: (value) => {
       if (deferred.settled) {
         return;
@@ -70443,21 +70661,21 @@ class SessionService {
       sessionKey: run.resolved.sessionKey
     };
     try {
-      const fresh = await this.runnerSessions.startFreshSession(target, params.timingContext);
+      const restarted = await this.runnerSessions.restartRunnerPreservingSessionId(target, params.timingContext);
       const currentRun = this.getRun(sessionKey, params.runId);
       if (!currentRun) {
         return true;
       }
       const restartedAt = Date.now();
-      currentRun.resolved = fresh.resolved;
+      currentRun.resolved = restarted.resolved;
       currentRun.steeringReady = false;
       currentRun.startedAt = restartedAt;
       currentRun.latestUpdate = this.createRunUpdate({
         resolved: currentRun.resolved,
         status: currentRun.latestUpdate.status === "detached" ? "detached" : "running",
         snapshot: "",
-        fullSnapshot: fresh.initialSnapshot,
-        initialSnapshot: fresh.initialSnapshot
+        fullSnapshot: restarted.initialSnapshot,
+        initialSnapshot: restarted.initialSnapshot
       });
       await this.sessionState.setSessionRuntime(currentRun.resolved, {
         state: "running",
@@ -70467,12 +70685,12 @@ class SessionService {
       this.startRunMonitor(sessionKey, {
         ...params,
         promptRetryAttempt: 1,
-        initialSnapshot: fresh.initialSnapshot,
+        initialSnapshot: restarted.initialSnapshot,
         startedAt: restartedAt
       });
       return true;
-    } catch (freshError) {
-      await this.failActiveRun(sessionKey, run.runId, await this.runnerSessions.mapRunError(freshError, run.resolved.sessionName, run.latestUpdate.fullSnapshot));
+    } catch (restartError) {
+      await this.failActiveRun(sessionKey, run.runId, await this.runnerSessions.mapRunError(restartError, run.resolved.sessionName, run.latestUpdate.fullSnapshot));
       return true;
     }
   }
@@ -70535,9 +70753,14 @@ class SessionService {
       if (!currentRun) {
         return true;
       }
+      if (await this.hasStoredResumableSessionId(currentRun.resolved)) {
+        await this.notifyRecoveryStep(currentRun, buildRunRecoveryNote("resume-failed"));
+        await this.failActiveRun(sessionKey, currentRun.runId, new Error(buildRunRecoveryNote("manual-new-required")));
+        return true;
+      }
       await this.notifyRecoveryStep(currentRun, buildRunRecoveryNote("fresh-attempt"));
       try {
-        await this.runnerSessions.startFreshSession(target, params.timingContext);
+        await this.runnerSessions.restartRunnerWithFreshSessionId(target, params.timingContext);
       } catch (freshError) {
         await this.failActiveRun(sessionKey, currentRun.runId, await this.runnerSessions.mapRunError(freshError, currentRun.resolved.sessionName, currentRun.latestUpdate.fullSnapshot));
         return true;
@@ -70546,6 +70769,13 @@ class SessionService {
       return true;
     }
   }
+  async hasStoredResumableSessionId(resolved) {
+    if (resolved.runner.sessionId.resume.mode !== "command") {
+      return false;
+    }
+    const entry = await this.sessionState.getEntry(resolved.sessionKey);
+    return Boolean(entry?.sessionId);
+  }
   startRunMonitor(sessionKey, params) {
     const run = this.getRun(sessionKey, params.runId);
     if (!run) {
@@ -70851,6 +71081,9 @@ class AgentService {
   async nudgeSession(target) {
     return this.runnerSessions.nudgeSession(target);
   }
+  async triggerNewSession(target) {
+    return this.runnerSessions.triggerNewSession(target);
+  }
   async getConversationFollowUpState(target) {
     return this.sessionState.getConversationFollowUpState(target);
   }
@@ -72668,6 +72901,23 @@ async function processChannelInteraction(params) {
       await params.agentService.recordConversationReply(params.sessionTarget);
       return interactionResult;
     }
+    if (slashCommand.name === "new") {
+      if (sessionBusy) {
+        await params.postText("This session is busy. Use `/stop` first if you want to interrupt it before triggering a new runner conversation.");
+        await params.agentService.recordConversationReply(params.sessionTarget);
+        return interactionResult;
+      }
+      const rotated = await params.agentService.triggerNewSession(params.sessionTarget);
+      await params.postText([
+        `Triggered a new runner conversation for agent \`${rotated.agentId}\`.`,
+        `sessionName: \`${rotated.sessionName}\``,
+        `storedSessionId: \`${rotated.sessionId ?? "none"}\``,
+        rotated.restartedRunner ? "No live runner existed, so clisbot opened a fresh runner session." : `triggerCommand: \`${rotated.command}\``
+      ].join(`
+`));
+      await params.agentService.recordConversationReply(params.sessionTarget);
+      return interactionResult;
+    }
     if (slashCommand.name === "nudge") {
       const nudged = await params.agentService.nudgeSession(params.sessionTarget);
       await params.postText(nudged.nudged ? `Sent one extra Enter to agent \`${nudged.agentId}\` session \`${nudged.sessionName}\`.` : `No active or resumable session to nudge for agent \`${nudged.agentId}\`.`);
@@ -82635,6 +82885,52 @@ async function runTimezoneCli(args) {
   throw new Error(renderTimezoneHelp());
 }
 
+// src/control/update-cli.ts
+var GITHUB_RAW_BASE = "https://raw.githubusercontent.com/longbkit/clisbot/main";
+function renderUpdateHelp() {
+  return [
+    `${renderCliCommand("update")} / ${renderCliCommand("update --help")}`,
+    "Prints this guide only. Direct update is not supported yet.",
+    "A bot can use this guide to update itself.",
+    "",
+    "Targets:",
+    "  stable/latest/default -> clisbot@latest",
+    "  beta                  -> clisbot@beta",
+    "  exact version         -> clisbot@<version>",
+    "",
+    "Flow:",
+    `  1. ${renderCliCommand("status")}`,
+    "  2. Read docs in priority order.",
+    "  3. npm install -g clisbot@<target> && clisbot restart",
+    `  4. ${renderCliCommand("status")}`,
+    "  5. Report version, health, manual action, and useful release-note highlights.",
+    "",
+    "Docs, read in order:",
+    `  1. Migration index: ${GITHUB_RAW_BASE}/docs/migrations/index.md`,
+    "     If Manual action: required, follow its runbook. If none, continue.",
+    `  2. Release quick info: ${GITHUB_RAW_BASE}/docs/releases/README.md`,
+    "     Use for release-note map and current release highlights.",
+    `  3. Update guide: ${GITHUB_RAW_BASE}/docs/update/README.md`,
+    "     Use for release notes, useful new features, things to try, and user-guide links.",
+    "  4. Full docs: https://github.com/longbkit/clisbot/tree/main/docs",
+    "     Use for deep questions. If needed, fetch or clone docs and inspect relevant files.",
+    "",
+    "Rules:",
+    "  - Use npm dist-tags, not highest semver.",
+    "  - Stable/latest is default; beta only when the user asks.",
+    "  - If install mode is not normal global npm, stop and ask."
+  ].join(`
+`);
+}
+async function runUpdateCli(args) {
+  const action = args[0];
+  if (!action || action === "--help" || action === "-h" || action === "help") {
+    console.log(renderUpdateHelp());
+    return;
+  }
+  throw new Error(renderUpdateHelp());
+}
+
 // src/control/activity-store.ts
 import { dirname as dirname16 } from "node:path";
 class ActivityStore {
@@ -84516,6 +84812,10 @@ async function runBuiltinCommand(command) {
     await logs(command.lines);
     return true;
   }
+  if (command.name === "update") {
+    await runUpdateCli(command.args);
+    return true;
+  }
   return false;
 }
 async function runControlCommand(command) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clisbot",
-  "version": "0.1.45-beta.4",
+  "version": "0.1.45-beta.5",
   "private": false,
   "description": "Chat surfaces for durable AI coding agents running in tmux",
   "license": "MIT",