# clisbot v0.1.50

Released: 2026-04-28

`v0.1.50` is the public release after `v0.1.43`. `v0.1.44` was kept as an internal pre-release branch and was not published as the public update target.

## Summary

`clisbot` now feels safer and more practical in real Slack and Telegram work:
shared-surface access is clearer, old installs update directly, long-running
coding sessions recover more truthfully, queued follow-up work is first-class,
and Telegram media plus richer sender or surface context make everyday chat
usage easier.

Most importantly, `v0.1.50` makes three chat-first workflows much easier to
understand and trust:

- ask naturally for a schedule, like "every weekday at 07:00 ..."
- ask naturally for the next follow-up pass, like "after this finishes ..."
- use `/new` when you want to reset into a fresh chat context for the current
  routed conversation

## Highlights

- Shared bots are safer to expose in real groups because surface admission and
  sender policy are now separate.
- Existing installs before `0.1.50` can update directly; clisbot backs up and
  updates compatible config shapes automatically.
- Long-running coding workflows are calmer to operate: delayed trust prompts,
  ambiguous `/new` capture paths, and restart stop-timeout races now surface
  more truthful behavior.
- Queued follow-up work is now a first-class product surface through chat
  `/queue` and `clisbot queues`.
- `/new` is now a clearer intentional control when you want the current routed
  conversation to start fresh instead of continuing the old agent context.
- Scheduled loops are more reliable: wall-clock schedules preserve timezone
  intent, and fresh Codex sessions wait until the prompt is ready before
  submitting.
- Agents receive clearer `sender` and `surface` context, including readable
  Slack and Telegram names when available.

## Important Chat Workflows

Three `v0.1.50` use cases deserve special attention because they make clisbot
feel more AI-native from normal chat instead of forcing operators back into the
CLI first.

### Create Schedules Through Chat With `/loop`

You can now treat normal chat itself as the front door for recurring work.
The important user-facing shift is not just that `/loop` exists, but that the
bot can increasingly help turn natural schedule requests into the right loop
flow.

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 this matters in `0.1.50`:

- wall-clock schedules preserve the resolved timezone when created
- the first scheduled Codex prompt waits for the runner to become ready
- creation replies are clearer about next run time and cancel flow

### Run Queue-First Workflow Through Chat With `/queue`

Queued follow-up is no longer just an implementation detail. It is now a real
product surface for same-session workflow control. The important user-facing
shift is that the next pass can be requested in normal chat, not only through a
manual operator command.

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 this matters in `0.1.50`:

- queued work is first-class through chat `/queue` and `clisbot queues`
- delayed work keeps better sender and surface context at delivery time
- per-session pending limits make queue-heavy workflows safer to operate

For heavy CLI-coding workflows, this can go further after installing the
`queue-workflow` skill through the user's usual `npx skills` install flow. Then
the user can say something like "use queue workflow for this task" plus the job
description, and the bot can automatically add stronger queued follow-up passes
instead of stopping after the first clean patch.

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

The third important chat-first workflow is knowing when to start fresh.

Example:

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

Why this matters in `0.1.50`:

- `/new` is now a first-class chat control for intentionally resetting the
  current routed conversation into a new agent session
- ambiguous `/new` capture failures now preserve stored session identity more
  truthfully instead of silently drifting or clearing state on weak evidence
- this makes "reset the chat context and continue cleanly" much easier to trust

## Highlights By Persona

### Personal User

- Your bot is easier to keep running during real coding sessions because
  restart, trust-prompt, and session-continuity behavior are less fragile.
- `/queue` gives you a simple way to stack the next prompt without babysitting
  the current run.
- Natural chat requests like "every weekday at 07:00 check CI for me" are now a
  much more practical front door into real scheduled workflows because timezone
  and first-prompt behavior are more trustworthy.
- `/new` is a much clearer escape hatch when you want to reset the current chat
  context and start a fresh session on purpose.
- Telegram `voice` and `audio` files now enter the workspace as normal
  attachments, which makes mobile and on-the-go workflows more useful.

### Shared Bot Owner

- Group safety is easier to reason about: "is this group admitted?" is now a
  different decision from "which people inside it may use the bot?"
- Existing installs can move to `0.1.50` directly with automatic backup and
  config rewrite instead of manual migration first.
- Topic and thread continuity are stricter, so shared surfaces are less likely
  to leak stale output into the wrong conversation.

### Operator

- `clisbot queues` gives you a durable queue surface instead of relying only on
  in-chat follow-up behavior.
- Chat-first workflow control is much stronger: a user can ask for recurring
  work or the next follow-up pass in normal conversation, and the bot can map
  that into real loop or queue behavior instead of forcing the operator to drop
  back into the CLI first.
- `/new` is easier to treat as a deliberate "reset this conversation" control
  instead of a fragile backend trick.
- `/whoami`, `/status`, and runner debug surfaces now expose session identity
  more truthfully, including whether the known `sessionId` is already
  persisted.
- Restart and runner recovery are easier to trust because stop-timeout races,
  delayed trust prompts, and ambiguous stale-resume paths are handled more
  explicitly.

### Power User Doing Long Coding Runs

- Prompt context is richer and more readable across normal chat, queued work,
  steering, and loops.
- Streaming and pane-boundary isolation are stricter, so active previews are
  less likely to show stale content from another run.
- Session continuity now preserves the stored mapping on weak evidence instead
  of silently drifting into a different native tool conversation.

## Operator Impact

- Biggest user-visible gains:
  - safer shared-surface defaults
  - direct upgrade path from older installs
  - first-class queue control
  - better truth around runner continuity and restart behavior
- Update safety: automatic direct update from versions before `0.1.50`.
- Manual action: none for normal updates from older installs to `0.1.50`.
- Existing configs from `0.1.43`, older legacy versions, and internal `0.1.44` pre-releases are backed up and updated automatically on first read.
- Shared Slack and Telegram surfaces now separate multi-user surface admission from sender policy inside admitted groups.
- Exact shared routes and Telegram topics should omit route-local `policy` when they intend to inherit `group:*`.
- Wall-clock loops now freeze the resolved timezone and include clearer schedule/cancel details.
- Codex scheduled-loop startup and streaming previews are safer, including better prompt-boundary isolation and native `Working...` timer preservation.
- Queue creation and inspection now exist as first-class operator surfaces through `clisbot queues`, including per-session pending limits.
- `clisbot restart` is now more truthful during updates when stop-timeout warnings race a worker that has already exited.
- Update guide: [update guide](../updates/update-guide.md).

## Functional Changes

### Channels

#### Added

- Added Telegram `voice` and `audio` attachment download into the agent workspace, passed to multimodal CLIs as normal file mentions.
- Added compact prompt `Message context` with `time`, `sender`, and `surface` across normal, steering, queue, and loop delivery paths.
- Added Slack sender and surface display enrichment through `users.info` and `conversations.info`, with stable id fallback when lookup is unavailable.
- Added Telegram topic display name enrichment from topic creation metadata and surface-directory records when current payloads do not carry topic names.
- Added Telegram native command-menu registration for `/new` with the clearer description `Start new session`.

#### Changed

- Updated Slack app manifest and setup docs to include the lookup scopes needed for readable sender and surface context: `users:read`, `channels:read`, `groups:read`, `im:read`, and `mpim:read`.
- Preserved known surface-directory display names and handles when later provider events only contain stable ids.
- Rebuilt queued, steering, and loop prompt envelopes at delivery time so delayed work does not reuse stale sender/surface context.

#### Fixed

- Fixed Telegram topic routing to treat `message_thread_id` as authoritative even when Telegram omits `chat.is_forum`.
- Fixed rendering guards so runner updates and finals are not delivered to the wrong channel interaction when `sessionKey` differs.
- Fixed streaming extraction to prefer the latest visible CLI prompt boundary before baseline diff, preventing old pane content from leaking into current previews.
- Fixed running previews so native CLI `Working...` timer lines are preserved instead of replaced by generic status text.
- Fixed live preview rendering when Codex leaves an empty idle input prompt below an active timer.

### Auth

#### Added

- Added enforced `allowUsers` and `blockUsers` behavior for shared group routes before messages reach the runner.
- Added wildcard shared-surface user controls through `group:*`, so operators can allow or block a principal across every admitted group under a bot.
- Added effective permission explanations in `clisbot auth get-permissions --sender <principal> --agent <id> --json`, including `runShellSlashCommand`.

#### Changed

- Separated multi-user surface admission (`groupPolicy` and Slack `channelPolicy`) from sender policy inside admitted groups (`groups["*"].policy` and exact route policy).
- Clarified that `disabled` means fully silent on that surface, including owner/admin and pairing guidance.
- Preserved the invariant that owner/admin can bypass sender allowlists only after a group is admitted; `blockUsers` still wins.

### Agents

#### Added

- Added chat `/new` to intentionally trigger a new runner conversation for the current routed session; Codex and Claude receive `/new`, Gemini receives `/clear`, then clisbot runs `/status` and stores the new `sessionId`.
- Added durable session-scoped queue items under `StoredSessionEntry.queues`, shared by chat `/queue`, route `additionalMessageMode: "queue"`, and `clisbot queues`.

#### Changed

- Stored creator metadata on CLI-created loops so scheduled prompts can render truthful sender context later.
- `/whoami` and `/status` now show `sessionName`, `sessionId`, and persistence annotation instead of presenting only persisted `storedSessionId` as identity truth.

#### Fixed

- Fixed Codex-backed loop runs so the first scheduled prompt waits for the interactive prompt marker before submission.
- Fixed existing live tmux session reuse when the stored CLI `sessionId` is missing: clisbot now captures the runner conversation id before the next user prompt instead of leaving that session permanently non-resumable.
- Fixed status-command session-id capture to read only the fresh `/status` interaction delta and ignore stale UUIDs in transcript history.
- Fixed Codex status-command session-id capture for boxed `/status` output, so `storedSessionId` is persisted after stale runner sunset and later prompts can resume the same CLI session.
- Fixed automatic runner retry and recovery paths so they preserve `sessionKey -> sessionId`; only explicit fresh-session or `/new` flows clear or rotate the stored runner conversation id.
- Fixed ambiguous stale-resume startup and `/new` capture failure behavior so clisbot preserves the stored session id instead of clearing it on weak evidence.
- Fixed fresh-runner startup visibility so when the runner is already usable but durable session-id capture still lags, the active chat surface gets a clear warning that the session is running but not yet resumable.

### Runners

#### Changed

- Pruned release-owned runner startup defaults from persisted config so Codex, Claude, Gemini, and runtime monitor defaults can inherit the current release behavior.
- Corrected Gemini compatibility status to fully compatible for routed Slack and Telegram workflows.

#### Fixed

- Fixed native runner timer recognition for ellipsis timer lines such as `Working... (2m 4s ...)`.
- Fixed runner recovery and prompt-boundary handling around stale pane content and active-run previews.

### Control

#### Added

- Added `clisbot queues list|status|create|clear` for app-wide or scoped durable queue inspection, explicit routed queue creation, and pending-only clear.
- Added `routes clear-policy` for exact shared routes that should inherit the wildcard shared policy.
- Added clearer route CLI help for canonical shared route ids, allow/block examples, and route policy behavior.
- Added runner debug shortcuts: `clisbot inspect` and `clisbot watch` now map to `clisbot runner inspect` and `clisbot runner watch`.
- Added `runner inspect --latest`, plus `--index <n>` selection for both `runner inspect` and `runner watch` using the order printed by `runner list`.

#### Changed

- CLI wall-clock loop creation now confirms the first schedule before persisting it, showing resolved timezone, next run, and the exact retry command with `--confirm`.
- `routes get-timezone` now prints the route override, effective timezone, and current local time for that surface.
- `runner inspect` now defaults to 100 lines when `--lines` is omitted.
- `clisbot queues create` now posts a queue-created acknowledgement on the target surface after persistence, including queue position and the submitted prompt.
- `clisbot runner list` now stays a lightweight tmux inventory and no longer captures every live pane just to infer session ids.

### Configuration

#### Added

- Added automatic config backup, migration, validation, and stage logging for updates from older installs to `0.1.50`.
- Added internal pre-release `0.1.44 -> 0.1.50` update support.
- Added `clisbot timezone get|set|clear|doctor` for the app-wide default timezone.
- Added scoped timezone commands for agents, routes, and concrete bots.
- Added optional `control.queue.maxPendingItemsPerSession`; when omitted, the current default remains `20`.

#### Changed

- Standardized stored bot config around `directMessages` and `groups` with raw provider-local ids plus `*`.
- Standardized CLI route ids around `dm:<id>`, `dm:*`, `group:<id>`, `group:*`, and `topic:<chatId>:<topicId>`.
- Kept Slack `channel:<id>`, `groups:*`, and older wildcard forms as compatibility input from released `0.1.43` configs and older CLI habits.
- Migrated legacy timezone defaults into `app.timezone` and removed the old default-level timezone fields.
- Decoupled default workspace bootstrap from OpenClaw reference templates by moving runtime bootstrap reads to `templates/default`.
- Kept exact shared routes without explicit sender policy inheriting `groups["*"].policy` instead of stamping `policy: open` everywhere.

#### Fixed

- Fixed migration of legacy exact shared routes that previously became `policy: disabled` during normalization.
- Fixed wildcard `directMessages["*"]` and `groups["*"]` ordering so default policy nodes remain first.
- Fixed exact DM route creation after wildcard reordering.
- Fixed Telegram topic mode persistence so topic-level streaming, response-mode, or additional-message overrides preserve the parent route admission flags instead of resetting them on the next config rewrite.

### DX

#### Added

- Added AI-discoverable prompt guidance telling agents to inspect `clisbot loops --help` for schedule, loop, and reminder requests.
- Added default bootstrap guidance asking agents to confirm timezone and local time before writing timezone notes.

#### Changed

- Updated README, setup docs, release docs, task docs, and CLI help so route ids, policy examples, timezone behavior, and Gemini status match the current runtime.

## Non-Functional Changes

### Stability

#### Changed

- Relaxed channel startup timeout handling for slower Slack Socket Mode handshakes.
- Froze resolved effective timezone on calendar loop records so later timezone config changes do not silently move existing schedules.

#### Fixed

- Fixed loop first-prompt submission in fresh Codex tmux panes.
- Increased the default Codex and Claude startup windows to match Gemini's 15s default, so slower CLI launches do not leave scheduled loops stuck after only the start notification.
- Fixed a stale-runner resume regression where Codex `/status` displayed a session id but the cleaned transcript path dropped boxed status rows before persistence.
- Fixed a stale-runner startup retry regression where clisbot cleared the stored native session id while restarting tmux, even though the logical session mapping should survive runner process cleanup.
- Fixed cross-topic/session isolation for Telegram topics.
- Fixed running preview rendering so streamed content keeps the latest active timer.
- Fixed stale tmux pane content extraction during running and completion snapshots.
- Fixed delayed workspace-trust handling so tmux runners accept active Codex, Claude, or Gemini trust prompts again before the first routed prompt or later steering input if that screen appears after startup.
- Fixed `clisbot restart` false failures during update or restart when `stop` times out but the monitor exits moments later; restart now rechecks runtime status briefly and continues into `start` when the service has actually stopped.
- Fixed live-runner `/new` retry behavior so clisbot retries session-id capture without blindly re-submitting `/new`, and surfaces one user-visible failure reply when capture or persistence still fails.
- Fixed operator active-run and queue reconciliation so stale `running` projections are cleared once the tmux session is gone or the session is truly idle.

### Security

#### Security

- Hardened shared-surface policy enforcement so disabled topic messages cannot fall back to parent group routing.
- Hardened prompt guidance with a read-only permission check before sensitive actions or clisbot configuration changes.
- Preserved `blockUsers` precedence over owner/admin allowlist bypass in admitted groups.

### Architecture Conformance

#### Changed

- Kept topic identity, sender/surface prompt context, route policy, and loop delivery aligned with the channel/configuration/agents boundary split.
- Kept persisted surface-directory records as structured ids and display metadata rather than prompt-rendered text.

## Update Notes

```text
Update path: direct
Manual action: none
Risk level: low
Automatic config update: yes
Breaking change: no
```

Existing configs from `0.1.43`, older legacy versions, and internal `0.1.44` pre-releases are updated automatically on first read and backed up first under `~/.clisbot/backups/`.

Recommended stable install:

```bash
npm install -g clisbot@0.1.50
clisbot restart
```

For the install/update checklist, use the [update guide](../updates/update-guide.md).

## Pre-Release History

- `v0.1.50-beta.1`: first beta line for the shared route, timezone, automatic config update, Gemini compatibility, default templates, Telegram audio, and prompt-context work.
- `v0.1.50-beta.2`: preserved native CLI `Working...` timer lines and tightened streaming extraction around the latest prompt boundary.
- `v0.1.50-beta.3`: added loop creator metadata and pruned release-owned runner startup defaults from persisted config.
- `v0.1.50-beta.4`: included relaxed channel startup timeout handling and the live-preview timer fix used by the current runtime validation.
- `v0.1.50-beta.5`: stabilizes runner startup defaults, tightens `/new` session triggering/capture retry, and removes confusing native-session wording from user-facing docs.
- `v0.1.50-beta.9`: hardens session ownership and runner isolation, fixes missing-`sessionId` live-runner reuse so surfaces cannot attach to a foreign tmux runner, simplifies persisted loop and queue prompt state, and refreshes the matching tests and docs before public release.
- `v0.1.50-beta.10`: preserves stored session ids on ambiguous resume and `/new` failures, narrows startup degradation to true persistence failures, and removes the `runner list` pane-capture cost regression.
- `v0.1.50-beta.11`: fixes delayed trust-prompt handling so tmux runners accept active Codex, Claude, or Gemini workspace trust screens before prompt submission or steering, and makes `clisbot restart` tolerate stop-timeout false failures when the runtime has actually exited.
- `v0.1.50-beta.12`: polishes the root README landing, adds npm download and MIT badges, and pushes the multilingual mirror pass further so localized root READMEs and glossary-owned wording are more consistent across Vietnamese, Simplified Chinese, and Korean.
- `v0.1.50-beta.13`: adds per-loop progress-message override control, updates loop CLI help and docs to explain inherit-vs-override behavior clearly, tightens queue-created notifications with queue ids, and adds the repo-local `web-diff-review` skill copy plus the Tailscale-access guidance update.
- `v0.1.50-beta.14`: fixes Slack mention gating so sender allowlists do not silently block already-mentioned messages, and adds the matching regression coverage for the mention-path behavior.

## Validation

Validated across the release branch with:

- targeted route, config, prompt-context, Telegram, tmux, text, interaction, and Slack manifest tests
- `bunx tsc --noEmit`
- `bun run check`
- `bun run build`

Notes:

- The live runtime was updated to `0.1.50-beta.12` and verified running with Slack and Telegram active after publish and restart.

## Links

- [Release guide](../updates/releases/v0.1.50-release-guide.md)
- [Update guide](../updates/update-guide.md)
- [Migration index](../migrations/index.md)
- [Channels](../user-guide/channels.md)
- [CLI Commands](../user-guide/cli-commands.md)
- [Authorization](../user-guide/auth-and-roles.md)
- [Configuration](../features/configuration/README.md)
- [Timezone config task](../tasks/features/configuration/2026-04-26-timezone-config-cli-and-loop-resolution.md)
- [Surface policy standardization task](../tasks/features/configuration/2026-04-24-surface-policy-shape-standardization-and-0.1.43-compatibility.md)
- [Prompt context sender/surface contract](../tasks/features/channels/2026-04-27-prompt-context-sender-surface-contract.md)