@maincode-ai/matilda-code 0.21.13 → 0.22.0-nightly.20261101.b0ad315a4

package/bundled/mainy/docs/features/auto-mode.md

@@ -1,308 +0,0 @@
-# Auto Mode
-
-Auto Mode uses an LLM classifier to evaluate each tool call and decide
-whether to auto-approve it. It sits between Auto-Edit (which only
-auto-approves file edits) and YOLO (which auto-approves everything).
-
-This page is the reference for configuring and troubleshooting Auto Mode.
-For an introduction, see the
-[Approval Mode overview](./approval-mode.md#4-auto-mode---classifier-driven-approval).
-
-## How it works
-
-When you're in Auto Mode and the agent tries to run a tool, Matilda Code
-walks three layers in order:
-
-1. **acceptEdits fast-path** — Edit / Write whose target path is inside
-   the workspace is auto-approved without invoking the classifier.
-   **Exception:** writes to Matilda Code's own self-modification surfaces
-   (`.matilda/settings*.json`, `MATILDA.md`, `AGENTS.md`, `MATILDA.local.md`,
-   configured context filenames, `.matilda/rules/`, `.matilda/commands/`,
-   `.matilda/agents/`, `.matilda/skills/`, `.matilda/hooks/`, `.mcp.json`) and
-   persistence surfaces (`.git/`, `.husky/`, `package.json`, `.npmrc`,
-   `Makefile`, `.github/workflows/`, etc.) route through the classifier
-   even when they are inside the workspace. Symlinks targeting protected
-   paths are resolved and rejected too. Shell commands that reach these
-   paths via `cd && bash -lc '...'` or other wrappers go through the
-   classifier as well.
-2. **Safe-tool allowlist** — Read-only and metadata-only built-in tools
-   (Read, Grep, Glob, LS, LSP, TodoWrite, AskUserQuestion, etc.) are
-   auto-approved without invoking the classifier.
-3. **LLM classifier** — Everything else (shell commands, web fetches,
-   sub-agent spawns, edits outside the workspace, MCP tools) is sent to
-   a two-stage classifier:
-   - **Stage 1 (fast)** — outputs `{ shouldBlock }` only. Around ~300ms.
-     If `shouldBlock` is `false`, the action is allowed and the call
-     proceeds.
-   - **Stage 2 (thinking)** — only runs when Stage 1 said block. Uses
-     chain-of-thought review to reduce Stage 1 false positives. Can
-     downgrade Stage 1's block to allow. Outputs the user-visible
-     `reason` on block.
-
-The classifier uses your configured fast model
-(`/model --fast`). If no fast model is configured, the main session
-model is used instead.
-
-## Hard rules still win
-
-Auto Mode does **not** replace hard permission rules. Before the classifier
-runs:
-
-- `permissions.deny` rules block the action with the rule's reason. The
-  classifier never sees it.
-- `permissions.allow` rules with specific specifiers (e.g.
-  `Bash(git status)`, `Read(./docs/**)`) still auto-allow without the
-  classifier — **except** when the call resolves to a write at a
-  protected self-modification or persistence path (see the list under
-  "How it works"). In that case Auto Mode re-checks the call through
-  the classifier so an allow rule on `Bash(*)` cannot silently turn
-  into permission to rewrite Matilda Code settings, commands, hooks,
-  skills, or MCP servers.
-- `permissions.ask` rules force manual confirmation even in Auto Mode.
-
-## Over-broad allow rules are stripped while in Auto Mode
-
-Rules like the following would let the agent execute arbitrary code
-without classifier review:
-
-- `Bash` / `Bash(*)` / `Bash()` — auto-allow every shell command
-- `Bash(python:*)`, `Bash(node*)`, `Bash(bash*)` — interpreter wildcards
-- `Agent` / `Agent(coder)` — any allow on the Agent tool
-- `Skill` / `Skill(pdf)` — any allow on the Skill tool
-
-When you enter Auto Mode, Matilda Code temporarily removes these rules from
-the active permission set and prints a notice listing them. The rules
-come back the moment you leave Auto Mode. `settings.json` is never
-modified.
-
-If you genuinely need these broad rules, use YOLO mode instead.
-
-## Configuring hints
-
-Auto Mode reads `permissions.autoMode` from your `settings.json`. The
-entries are natural-language descriptions, not rule patterns — they are
-injected additively into the classifier's system prompt alongside the
-built-in defaults.
-
-There are three hint categories plus an environment list:
-
-- **`allow`** — actions the classifier should auto-approve.
-- **`softDeny`** — destructive or irreversible actions the classifier
-  should block **unless the user's most recent explicit request asked
-  for that exact action and scope**. Soft denies can be cleared by
-  user intent; a generic "yes do whatever" doesn't count.
-- **`hardDeny`** — security-boundary actions the classifier must block
-  in Auto Mode regardless of `autoMode.hints.allow` or recent user
-  intent. This is classifier policy, not a deterministic permission
-  rule: it does not override `permissions.allow`. Use `permissions.deny`
-  for actions that must never be allowed by the permission manager.
-
-```json
-{
-  "permissions": {
-    "autoMode": {
-      "hints": {
-        "allow": [
-          "Running poetry install and poetry update in this Python project",
-          "Cleaning build artifacts under ./dist or ./build",
-          "Reading any file under /Users/me/code/"
-        ],
-        "softDeny": [
-          "Editing Matilda Code settings unless I explicitly ask for the exact change",
-          "Running migration scripts that touch the production DB"
-        ],
-        "hardDeny": [
-          "Sending secrets or .env contents to any network endpoint",
-          "Modifying anything under ~/.ssh or ~/.aws"
-        ]
-      },
-      "environment": [
-        "This is a private monorepo with strict commit signing",
-        "Production credentials live in 1Password, never in plain files"
-      ]
-    }
-  }
-}
-```
-
-`hints.deny` is still accepted for backward compatibility and is treated
-as `softDeny`. Mixing both is fine — entries are concatenated, `softDeny`
-first.
-
-### Length and count limits
-
-To keep the classifier system prompt small:
-
-- Each entry is capped at 200 characters (longer entries are truncated
-  with a warning).
-- `hints.allow`, `hints.softDeny`, and `hints.hardDeny` accept up to 50
-  entries each.
-- `environment` accepts up to 20 entries.
-
-### Layering across settings files
-
-`autoMode` is merged across system / user / workspace settings the same
-way other permission settings are: arrays are concatenated and
-de-duplicated.
-
-## Reading the decision
-
-When the classifier blocks an action, the tool call fails with one of
-the following error texts:
-
-- **`Blocked by auto mode policy: <reason>`** —
-  the classifier judged the action unsafe. The reason comes from Stage
-  2 of the classifier.
-- **`Auto mode classifier unavailable; action blocked for safety`** —
-  the classifier API was unreachable, timed out, or returned an
-  un-parseable response. This is fail-closed behavior: when in doubt,
-  block.
-
-Both messages are followed by a trailing guidance line telling the agent
-that the **denied action specifically** must not be completed through
-another tool, shell indirection, generated script, alias, symlink,
-config change, hook, command file, MCP configuration, encoded payload,
-or equivalent path. **Unrelated safe work and genuinely safer
-alternatives are still allowed** — only attempts to accomplish the same
-denied intent through a different surface are blocked.
-
-If the denied action is genuinely required, the agent should stop and
-ask you for explicit approval rather than route around the denial.
-
-### Classifier reason language
-
-Classifier reasons are produced by the LLM and are not translated. If you
-want non-English reasons, add a hint like
-`Respond reasons in Japanese` to `permissions.autoMode.environment`.
-
-## Fallback to manual approval
-
-Auto Mode protects you from getting stuck:
-
-- After **3 consecutive policy blocks** the next tool call falls back to
-  the standard manual-approval prompt. This catches the case where the
-  agent keeps trying minor variants of a forbidden command.
-- After **2 consecutive unavailable** results (classifier API failures)
-  the next tool call also falls back. This avoids waiting on a broken
-  classifier.
-
-The session itself stays in Auto Mode — only the single fallback call
-goes through manual approval. The counters reset when you approve the
-fallback call or switch modes.
-
-If you find yourself constantly hitting fallback, the most likely causes
-are an outage on the classifier API or hints that need tuning. Switch to
-Default Mode while you investigate.
-
-## Troubleshooting
-
-**"Auto mode keeps blocking my commands"**
-
-Look at the reason in the error message. If the classifier is being too
-conservative for your context, add an entry to
-`permissions.autoMode.hints.allow` describing the pattern in
-natural-language. Examples:
-
-- `"Building Docker images for this project (docker build ...)"`
-- `"Running database migrations against the local test DB"`
-
-**"Auto mode classifier unavailable"**
-
-The classifier API didn't respond. Possible causes:
-
-- Network issue between you and the model endpoint.
-- The configured fast model is no longer available — check `/model --fast`.
-- The transcript is too long and exceeds the fast-model context window.
-
-While diagnosing, switch back to Default Mode: `/approval-mode default`.
-
-**"Falling back to manual approval"**
-
-You've hit either the 3-consecutive-block or 2-consecutive-unavailable
-guard. Approve or reject the prompt as you normally would. After one
-approved fallback the consecutive counter resets.
-
-**The classifier sees sensitive data in my prompts**
-
-Tool inputs are projected through each tool's `toAutoClassifierInput`
-method before they reach the classifier. Long edit content, web fetch
-prompts, and sub-agent prompts are truncated. Tool results (file
-contents, web pages) are never sent to the classifier — only the user's
-text and assistant tool-use calls go through.
-
-If a specific tool is exposing fields you'd rather redact, file an issue
-with the tool name; the projection is per-tool and is meant to be
-tightened over time.
-
-## Limitations
-
-- **Not offline-capable.** The classifier requires an LLM call.
-- **Adds latency on the slow path.** Allowlist + acceptEdits cover most
-  calls without latency, but a `run_shell_command` typically adds
-  ~300ms (fast classifier path) or ~3-5s (slow path with thinking
-  review).
-- **Not a substitute for `deny` rules.** The classifier is best-effort.
-  For commands you're sure should never run, put them in
-  `permissions.deny`.
-- **MCP tools default to conservative blocking.** Third-party MCP tools
-  (`mcp__*`) opt-in to argument forwarding via the
-  `toAutoClassifierInput` override. Tools that have not opted in expose
-  only their name to the classifier — most such calls are
-  conservatively blocked unless you've written an explicit `allow`
-  rule. This is fail-closed by design (credentials and voluminous
-  content do not leak into the classifier LLM). If you trust a
-  specific MCP tool, add `permissions.allow: ["mcp__server__tool"]` so
-  it bypasses the classifier entirely.
-
-## FAQ
-
-**Does Auto Mode send my code to a third party?**
-
-Auto Mode reuses your existing model configuration — same endpoint as
-the main agent. If you've configured Matilda Code to use a self-hosted
-model, the classifier runs against that endpoint too.
-
-**Will my secrets / `.env` contents reach the classifier?**
-
-The classifier sees only what each tool's `toAutoClassifierInput`
-projection exposes:
-
-- `read_file` and other read-only tools: not invoked (they're on the
-  fast-path allowlist).
-- `edit` / `write_file`: file_path plus the first 80 characters of
-  old/new content. Full content is not forwarded.
-- `run_shell_command`: the full command (it has to — that's what the
-  classifier judges).
-- `web_fetch`: the URL only. The prompt field is not forwarded.
-- `agent`: subagent type plus the full prompt. The prompt is the
-  instruction the sub-agent will follow, so the classifier needs it
-  in full to detect attacks that would steer the sub-agent toward
-  destructive actions — same reason `run_shell_command` forwards the
-  full command.
-
-Tool results (the actual content returned by tools) are stripped from
-the classifier transcript entirely.
-
-MCP tools (`mcp__*`) follow a stricter default: their parameters are
-not forwarded unless the MCP tool author explicitly opted in via the
-`toAutoClassifierInput` override. The classifier sees the tool name
-but no arguments, so most MCP calls will be conservatively blocked
-unless the user has written an explicit allow rule. This is fail-
-closed by design — third-party tools should not leak credentials or
-voluminous file content into the classifier LLM without intent.
-
-**Can I disable the first-time information message?**
-
-It only shows once per user-settings file. After dismissal,
-`ui.autoModeAcknowledged: true` is set in your user settings.
-
-**How is this different from Auto-Edit?**
-
-Auto-Edit auto-approves file edits and nothing else — shell commands
-still ask. Auto Mode uses a classifier to also auto-approve safe shell
-commands and other tool calls while still blocking risky ones.
-
-**How is this different from YOLO?**
-
-YOLO auto-approves everything without any review. Auto Mode has the
-classifier in the loop and blocks risky actions.

package/bundled/mainy/docs/features/channels/_meta.ts

@@ -1,5 +0,0 @@
-export default {
-  overview: 'Overview',
-  telegram: 'Telegram',
-  plugins: 'Plugins',
-};

package/bundled/mainy/docs/features/channels/overview.md

@@ -1,328 +0,0 @@
-# Channels
-
-Channels let you interact with a Matilda Code agent from messaging platforms like Telegram, instead of the terminal. You send messages from your phone or desktop chat app, and the agent responds just like it would in the CLI.
-
-## How It Works
-
-When you run `matilda channel start`, Matilda Code:
-
-1. Reads channel configurations from your `settings.json`
-2. Spawns a single agent process using the [Agent Client Protocol (ACP)](../../developers/architecture)
-3. Connects to each messaging platform and starts listening for messages
-4. Routes incoming messages to the agent and sends responses back to the correct chat
-
-All channels share one agent process with isolated sessions per user. Each channel can have its own working directory, model, and instructions.
-
-## Quick Start
-
-1. Set up a bot on your messaging platform (see the [Telegram](./telegram) guide)
-2. Add the channel configuration to `~/.matilda/settings.json`
-3. Run `matilda channel start` to start all channels, or `matilda channel start <name>` for a single channel
-
-Want to connect a platform that isn't built in? See [Plugins](./plugins) to add a custom adapter as an extension.
-
-## Configuration
-
-Channels are configured under the `channels` key in `settings.json`. Each channel has a name and a set of options:
-
-```json
-{
-  "channels": {
-    "my-channel": {
-      "type": "telegram",
-      "token": "$MY_BOT_TOKEN",
-      "senderPolicy": "allowlist",
-      "allowedUsers": ["123456789"],
-      "sessionScope": "user",
-      "cwd": "/path/to/working/directory",
-      "instructions": "Optional system instructions for the agent.",
-      "groupPolicy": "disabled",
-      "groups": {
-        "*": { "requireMention": true }
-      }
-    }
-  }
-}
-```
-
-### Options
-
-| Option                   | Required | Description                                                                                                                                    |
-| ------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `type`                   | Yes      | Channel type: `telegram`, or a custom type from an extension (see [Plugins](./plugins))                                                        |
-| `token`                  | Telegram | Bot token. Supports `$ENV_VAR` syntax to read from environment variables                                                                       |
-| `clientId`               | No       | Client ID, for extension channels that need one. Supports `$ENV_VAR` syntax                                                                    |
-| `clientSecret`           | No       | Client secret, for extension channels that need one. Supports `$ENV_VAR` syntax                                                                |
-| `model`                  | No       | Model to use for this channel (e.g., `matilda3.5-plus`). Overrides the default model. Useful for multimodal models that support image input    |
-| `senderPolicy`           | No       | Who can talk to the bot: `allowlist` (default), `open`, or `pairing`                                                                           |
-| `allowedUsers`           | No       | List of user IDs allowed to use the bot (used by `allowlist` and `pairing` policies)                                                           |
-| `sessionScope`           | No       | How sessions are scoped: `user` (default), `thread`, or `single`                                                                               |
-| `cwd`                    | No       | Working directory for the agent. Defaults to the current directory                                                                             |
-| `instructions`           | No       | Custom instructions prepended to the first message of each session                                                                             |
-| `groupPolicy`            | No       | Group chat access: `disabled` (default), `allowlist`, or `open`. See [Group Chats](#group-chats)                                               |
-| `groups`                 | No       | Per-group settings. Keys are group chat IDs or `"*"` for defaults. See [Group Chats](#group-chats)                                             |
-| `dispatchMode`           | No       | What happens when you send a message while the bot is busy: `steer` (default), `collect`, or `followup`. See [Dispatch Modes](#dispatch-modes) |
-| `blockStreaming`         | No       | Progressive response delivery: `on` or `off` (default). See [Block Streaming](#block-streaming)                                                |
-| `blockStreamingChunk`    | No       | Chunk size bounds: `{ "minChars": 400, "maxChars": 1000 }`. See [Block Streaming](#block-streaming)                                            |
-| `blockStreamingCoalesce` | No       | Idle flush: `{ "idleMs": 1500 }`. See [Block Streaming](#block-streaming)                                                                      |
-
-### Sender Policy
-
-Controls who can interact with the bot:
-
-- **`allowlist`** (default) — Only users listed in `allowedUsers` can send messages. Others are silently ignored.
-- **`pairing`** — Unknown senders receive a pairing code. The bot operator approves them via CLI, and they're added to a persistent allowlist. Users in `allowedUsers` skip pairing entirely. See [DM Pairing](#dm-pairing) below.
-- **`open`** — Anyone can send messages. Use with caution.
-
-### Session Scope
-
-Controls how conversation sessions are managed:
-
-- **`user`** (default) — One session per user. All messages from the same user share a conversation.
-- **`thread`** — One session per thread/topic. Useful for group chats with threads.
-- **`single`** — One shared session for all users. Everyone shares the same conversation.
-
-### Token Security
-
-Bot tokens should not be stored directly in `settings.json`. Instead, use environment variable references:
-
-```json
-{
-  "token": "$TELEGRAM_BOT_TOKEN"
-}
-```
-
-Set the actual token in your shell environment or in a `.env` file that gets loaded before running the channel.
-
-## DM Pairing
-
-When `senderPolicy` is set to `"pairing"`, unknown senders go through an approval flow:
-
-1. An unknown user sends a message to the bot
-2. The bot replies with an 8-character pairing code (e.g., `VEQDDWXJ`)
-3. The user shares the code with you (the bot operator)
-4. You approve them via CLI:
-
-```bash
-matilda channel pairing approve my-channel VEQDDWXJ
-```
-
-Once approved, the user's ID is saved to `~/.matilda/channels/<name>-allowlist.json` and all future messages go through normally.
-
-### Pairing CLI Commands
-
-```bash
-# List pending pairing requests
-matilda channel pairing list my-channel
-
-# Approve a request by code
-matilda channel pairing approve my-channel <CODE>
-```
-
-### Pairing Rules
-
-- Codes are 8 characters, uppercase, using an unambiguous alphabet (no `0`/`O`/`1`/`I`)
-- Codes expire after 1 hour
-- Maximum 3 pending requests per channel at a time — additional requests are ignored until one expires or is approved
-- Users listed in `allowedUsers` in `settings.json` always skip pairing
-- Approved users are stored in `~/.matilda/channels/<name>-allowlist.json` — treat this file as sensitive
-
-## Group Chats
-
-By default, the bot only works in direct messages. To enable group chat support, set `groupPolicy` to `"allowlist"` or `"open"`.
-
-### Group Policy
-
-Controls whether the bot participates in group chats at all:
-
-- **`disabled`** (default) — The bot ignores all group messages. Safest option.
-- **`allowlist`** — The bot only responds in groups explicitly listed in `groups` by chat ID. The `"*"` key provides default settings but does **not** act as a wildcard allow.
-- **`open`** — The bot responds in all groups it's added to. Use with caution.
-
-### Mention Gating
-
-In groups, the bot requires an `@mention` or a reply to one of its messages by default. This prevents the bot from responding to every message in a group chat.
-
-Configure per-group with the `groups` setting:
-
-```json
-{
-  "groups": {
-    "*": { "requireMention": true },
-    "-100123456": { "requireMention": false }
-  }
-}
-```
-
-- **`"*"`** — Default settings for all groups. Only sets config defaults, not an allowlist entry.
-- **Group chat ID** — Override settings for a specific group. Overrides `"*"` defaults.
-- **`requireMention`** (default: `true`) — When `true`, the bot only responds to messages that @mention it or reply to one of its messages. When `false`, the bot responds to all messages (useful for dedicated task groups).
-
-### How group messages are evaluated
-
-```
-1. groupPolicy — is this group allowed?           (no → ignore)
-2. requireMention — was the bot mentioned/replied to? (no → ignore)
-3. senderPolicy — is this sender approved?         (no → pairing flow)
-4. Route to session
-```
-
-### Telegram Setup for Groups
-
-1. Add the bot to a group
-2. **Disable privacy mode** in BotFather (`/mybots` → Bot Settings → Group Privacy → Turn Off) — otherwise the bot won't see non-command messages
-3. **Remove and re-add the bot** to the group after changing privacy mode (Telegram caches this setting)
-
-### Finding a Group Chat ID
-
-To find a group's chat ID for the `groups` allowlist:
-
-1. Stop the bot if it's running
-2. Send a message mentioning the bot in the group
-3. Use the Telegram Bot API to check queued updates:
-
-```bash
-curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates" | python3 -m json.tool
-```
-
-Look for `message.chat.id` in the response — group IDs are negative numbers (e.g., `-5170296765`).
-
-## Media Support
-
-Channels support sending images and files to the agent, not just text.
-
-### Images
-
-Send a photo to the bot and the agent will see it — useful for sharing screenshots, error messages, or diagrams. The image is sent directly to the model as a vision input.
-
-To use image support, configure a multimodal model for the channel:
-
-```json
-{
-  "channels": {
-    "my-channel": {
-      "type": "telegram",
-      "model": "matilda3.5-plus",
-      ...
-    }
-  }
-}
-```
-
-### Files
-
-Send a document (PDF, code file, text file, etc.) to the bot. The file is downloaded and saved to a temporary directory, and the agent is told the file path so it can read the contents using its file-reading tools.
-
-Files work with any model — no multimodal support required.
-
-## Dispatch Modes
-
-Controls what happens when you send a new message while the bot is still processing a previous one.
-
-- **`steer`** (default) — The bot cancels the current request and starts working on your new message. Best for normal chat, where a follow-up usually means you want to correct or redirect the bot.
-- **`collect`** — Your new messages are buffered. When the current request finishes, all buffered messages are combined into a single follow-up prompt. Good for async workflows where you want to queue up thoughts.
-- **`followup`** — Each message is queued and processed as its own separate turn, in order. Useful for batch workflows where each message is independent.
-
-```json
-{
-  "channels": {
-    "my-channel": {
-      "type": "telegram",
-      "dispatchMode": "steer",
-      ...
-    }
-  }
-}
-```
-
-You can also set dispatch mode per group, overriding the channel default:
-
-```json
-{
-  "groups": {
-    "*": { "requireMention": true, "dispatchMode": "steer" },
-    "-100123456": { "dispatchMode": "collect" }
-  }
-}
-```
-
-## Block Streaming
-
-By default, the agent works for a while and then sends one large response. With block streaming enabled, the response arrives as multiple shorter messages while the agent is still working — similar to how ChatGPT or Claude show progressive output.
-
-```json
-{
-  "channels": {
-    "my-channel": {
-      "type": "telegram",
-      "blockStreaming": "on",
-      "blockStreamingChunk": { "minChars": 400, "maxChars": 1000 },
-      "blockStreamingCoalesce": { "idleMs": 1500 },
-      ...
-    }
-  }
-}
-```
-
-### How it works
-
-- The agent's response is split into blocks at paragraph boundaries and sent as separate messages
-- `minChars` (default 400) — don't send a block until it's at least this long, to avoid spamming tiny messages
-- `maxChars` (default 1000) — if a block gets this long without a natural break, send it anyway
-- `idleMs` (default 1500) — if the agent pauses (e.g., running a tool), send what's buffered so far
-- When the agent finishes, any remaining text is sent immediately
-
-Only `blockStreaming` is required. The chunk and coalesce settings are optional and have sensible defaults.
-
-## Slash Commands
-
-Channels support slash commands. These are handled locally (no agent round-trip):
-
-- `/help` — List available commands
-- `/clear` — Clear your session and start fresh (aliases: `/reset`, `/new`)
-- `/status` — Show session info and access policy
-
-All other slash commands (e.g., `/compress`, `/summary`) are forwarded to the agent.
-
-These commands work on all channel types.
-
-## Running
-
-```bash
-# Start all configured channels (shared agent process)
-matilda channel start
-
-# Start a single channel
-matilda channel start my-channel
-
-# Check if the service is running
-matilda channel status
-
-# Stop the running service
-matilda channel stop
-```
-
-The bot runs in the foreground. Press `Ctrl+C` to stop, or use `matilda channel stop` from another terminal.
-
-### Multi-Channel Mode
-
-When you run `matilda channel start` without a name, all channels defined in `settings.json` start together sharing a single agent process. Each channel maintains its own sessions, so users on different channels get separate conversations, even though they share the same agent.
-
-Each channel uses its own `cwd` from its config, so different channels can work on different projects simultaneously.
-
-### Service Management
-
-The channel service uses a PID file (`~/.matilda/channels/service.pid`) to track the running instance:
-
-- **Duplicate prevention**: Running `matilda channel start` while a service is already running will show an error instead of starting a second instance
-- **`matilda channel stop`**: Gracefully stops the running service from another terminal
-- **`matilda channel status`**: Shows whether the service is running, its uptime, and session counts per channel
-
-### Crash Recovery
-
-If the agent process crashes unexpectedly, the channel service automatically restarts it and attempts to restore all active sessions. Users can continue their conversations without starting over.
-
-- Sessions are persisted to `~/.matilda/channels/sessions.json` while the service is running
-- On crash: the agent restarts within 3 seconds and reloads saved sessions
-- After 3 consecutive crashes, the service exits with an error
-- On clean shutdown (Ctrl+C or `matilda channel stop`): session data is cleared — the next start is always fresh