# clisbot v0.1.50 Release Guide

Date: 2026-04-28

## Read This If

- You run a `0.1.43` clisbot install and plan to update.
- You use Slack or Telegram groups, Telegram topics, loops, or streaming previews.
- You rely on clisbot agents to change routes, auth, schedules, or runtime config from chat.

## TL;DR

This release makes clisbot safer for real group and topic usage: shared-surface access is clearer, config update is automatic, scheduled loops and durable queue control are more reliable, prompt context is more readable, and startup or restart truth stays stricter about the right session.

Three especially important day-to-day use cases are now much clearer in chat
itself:

- ask the bot naturally for recurring work, like "every day at 7am ..."
- ask the bot naturally for the next pass, like "after this finishes, do ..."
- use `/new` when you want to reset into a fresh chat context on purpose

## Pick Your Path

### If You Run A Personal Bot

- care most about: `/queue`, better long-run continuity, better trust-prompt
  recovery, and Telegram media attachments
- do after update: run one normal coding task, then verify `/status` and one
  queued follow-up

### If You Own A Shared Team Bot

- care most about: clearer `group:*` policy model, safer route inheritance, and
  stricter thread or topic isolation
- do after update: inspect the shared routes that matter, then verify one real
  group or topic conversation

### If You Operate The Runtime

- care most about: direct upgrade from older installs, `clisbot queues`, more
  truthful `sessionId` surfaces, and restart false-failure tolerance
- do after update: run `clisbot status`, `clisbot queues list`, and one
  targeted restart check

## What Changed

- Shared group access is easier to reason about: multi-user surface admission and sender policy are now separate.
- Configs from `0.1.43` are backed up and updated automatically to schema `0.1.50`.
- Wall-clock loops now have stronger timezone handling and better first-prompt reliability.
- Durable same-session queue control now exists through `clisbot queues` and chat `/queue`, with a per-session pending limit.
- Prompts now include compact sender and surface context across normal, queue, steering, and loop paths.
- Telegram voice/audio files now reach agent workspaces as attachments.
- Telegram topics and streaming previews have stronger session isolation so old pane content and wrong-topic updates are not rendered as the current answer.
- Session continuity and runner truth are tighter: ambiguous resume or `/new` failures preserve the stored session id, delayed trust prompts are re-accepted before prompt submission, and restart tolerates stop-timeout false failures when the worker already exited.

## Three Important Chat Use Cases

### 1. Create Schedules Directly From Chat

You no longer need to think of scheduling as a CLI-only operator task first.
For many cases, the normal chat interface is now the right entry point.

Examples:

- "Every weekday at 07:00, check CI and summarize failures for me."
- "Every night at 21:30, review tomorrow's calendar and draft priorities."
- "For the next incident, every 5 minutes watch deploy health until it is closed."

Why `0.1.50` makes this more trustworthy:

- wall-clock loops now freeze their resolved timezone
- fresh Codex loop runs wait for the prompt marker before submission
- the creation response is clearer about next run time and cancellation
- slash-command and CLI loop controls still exist, but the important product
  direction here is that normal chat can increasingly be the front door

### 2. Run Queue-First Workflow Directly From Chat

Queued follow-up is now a real workflow surface, not just a fallback when the
session is busy.

Examples:

- "After this patch, run a breadth review for regressions."
- "When the current task finishes, simplify naming and remove duplication."
- "Once the build is green, write the release summary and next-step brief."

Why `0.1.50` makes this more useful:

- `/queue` and `clisbot queues` now share the same durable queue model
- delayed queued prompts rebuild prompt context at delivery time
- per-session pending limits make queue-heavy workflows safer
- the intended user experience is increasingly "say the next step in chat" and
  let the bot translate that into durable queue behavior

For people who live in CLI coding tools, there is one stronger pattern worth
calling out explicitly: after installing the `queue-workflow` skill through
their usual `npx skills` install flow, they can say "use queue workflow for
this task" plus the work description and let the bot expand that into a
multi-pass queued workflow automatically.

### 3. Reset Chat Context Intentionally With `/new`

The third important chat workflow is knowing when to start fresh instead of
continuing the old agent conversation.

Examples:

- `/new`
- "Start a fresh session for this conversation."

Why `0.1.50` makes this more trustworthy:

- `/new` is a clearer first-class chat control for resetting the current routed
  conversation into a fresh session
- ambiguous `/new` capture failures now preserve stored session identity more
  truthfully instead of silently drifting or clearing state on weak evidence
- this makes intentional context reset much safer during long coding runs

## Most Noticeable Improvements

### Everyday Chat User

- queued follow-up now feels like a real feature, not a fragile workaround
- sender and surface context are easier for the agent to interpret correctly
- Telegram mobile workflows improve because `voice` and `audio` become normal
  workspace files

### Shared-Surface Admin

- group and topic exposure is easier to reason about safely
- route inheritance is clearer when you want exact surfaces to follow
  `group:*`
- old config shapes can be upgraded in place without a manual rewrite pass

### Debugging Operator

- restart warnings are less noisy because clisbot now distinguishes "stop was
  late" from "runtime is still actually up"
- session continuity is less likely to drift silently after stale resume or
  `/new` problems
- trust-prompt reappearance after upstream CLI changes is handled more
  intentionally before prompt submission

## What To Use Now

- Use `topic:<chatId>:<topicId>` for Telegram topic routes.
- Use `group:*` as the default shared sender policy node for one bot.
- Use exact group or topic routes without route-local `policy` when they should inherit from `group:*`.
- Use `clisbot timezone get|set|clear|doctor` for app-level timezone control.
- Use natural requests like "every weekday at 07:00 ..." when you want the bot
  to help create a real schedule from chat.
- Use natural requests like "after this finishes, ..." when you want the next
  pass to wait behind the current run without losing same-session context.
- Use `/new` when you want to reset the current chat context and continue in a
  fresh session on purpose.
- If you use CLI coding tools heavily, install the `queue-workflow` skill with
  your usual `npx skills` flow, then explicitly say "use queue workflow" plus
  the task description when you want the bot to push itself into stronger
  queued follow-up execution.
- Use `clisbot queues list|status|create|clear` for durable queue operations instead of ad hoc follow-up reminders.
- Ask agents to run `clisbot auth get-permissions --sender <principal> --agent <id> --json` before sensitive config changes.

## What To Watch

- Existing exact shared routes should not unexpectedly carry `policy: disabled`.
- Calendar loops freeze their resolved timezone when created; changing app timezone later should not move existing loops.
- Slack display enrichment needs the lookup scopes documented in the Slack manifest guide.
- Streaming fixes are intentionally strict about prompt boundaries; report any case where old pane content or another topic's output appears in a new answer.
- If restart prints a stop-timeout warning during update, the current release should still continue cleanly when status already shows the worker exited; report it only if restart really leaves the runtime down.
- If a workspace trust prompt appears again after a CLI update, the routed prompt should still proceed; report it if trust remains visible after the first routed prompt or steering attempt.

## Update / Rollout

- Install or run the `0.1.50` package.
- Restart clisbot and let the automatic config update run.
- Confirm `clisbot status` reports schema/runtime health.
- Check Telegram topic routes and any Slack shared routes that matter.
- If you use queue-heavy workflows, verify `clisbot queues list` and one queued prompt on a real route.
- Keep the backup under `~/.clisbot/backups/` until the updated runtime is stable.

## Good First Checks

- Personal Telegram bot: one normal prompt, one `/queue ...`, one `/status`
- Personal or shared bot: ask for one real natural-language schedule such as
  "every weekday at 07:00 check CI for me", then verify the returned timezone,
  next run time, and cancel flow
- Shared Slack or Telegram surface: one real message in the target thread or
  topic plus one route-permission check
- Runtime operator: one `clisbot restart`, one `clisbot runner list`, one
  `clisbot queues list`

## Links

- [Release note](../../releases/v0.1.50.md)
- [Update guide](../update-guide.md)
- [Migration index](../../migrations/index.md)
- [Changelog](../../../CHANGELOG.md)
