@songsid/agend 2.2.0-beta.1 → 2.2.0-beta.3

package/dist/general-knowledge/skills/backend-providers/SKILL.md

@@ -14,7 +14,7 @@ AgEnD selects a provider; the backend CLI owns endpoint and credential definitio
 |---|---|
 | Codex | Select with `backend_options.codex.provider`; define the provider in Codex `config.toml`. |
 | OpenCode | Define the provider in `opencode.json`; use model ID `<provider>/<model>`. |
-| Claude Code, Kiro CLI, Antigravity, Grok | Provider is fixed by the CLI; do not set `backend_options` for provider selection. |
+| Claude Code, Kiro CLI, Antigravity, Grok, Muse | Provider is fixed by the CLI; do not set `backend_options` for provider selection. |
 
 ## Create a Codex custom-provider instance
 

package/dist/general-knowledge/skills/credential-profiles/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: credential-profiles
-description: Run agents on more than one subscription of the same backend. Use when someone asks for a worker on a different account, wants an agent moved to another subscription, or asks which subscription an agent is using. Currently kiro-cli only.
+description: Run agents on more than one subscription of the same backend. Use when someone asks for a worker on a different account, wants an agent moved to another subscription, or asks which subscription an agent is using. Currently kiro-cli and codex.
 roles: [general]
 ---
 
@@ -47,8 +47,8 @@ CODEX_HOME="${AGEND_HOME:-~/.agend}/credential-profiles/codex/<profile>" codex l
 
 ```
 create_instance(
-  name: "research-b",
-  working_directory: "/home/you/projects/app",
+  topic_name: "research-b",
+  directory: "/home/you/projects/app",
   backend: "kiro-cli",
   backend_options: { "kiro-cli": { "credential_profile": "personal" } },
 )
@@ -66,8 +66,10 @@ update_instance_config(
 )
 ```
 
-The credentials are read when the CLI starts, so **the instance is restarted
-for you** and the reply says `restarted: true`.
+The credentials are read when the CLI starts, so a running instance **is
+restarted for you** and the reply says `restarted: true`. A paused or stopped one
+is not started: the reply says `restarted: false`, and the switch applies at its
+next start.
 
 **For kiro**, a switch is always a **new conversation**, and the reply says so
 (`conversation_carried_over: false`). kiro keeps its conversations in the same
@@ -116,7 +118,8 @@ Say "the default login", not "no subscription".
 `get_usage` returns one row per subscription: `Kiro (work)` and
 `Kiro (personal)` rather than a single `Kiro`. Read them out separately — they
 are two quotas, and adding them together would give a number that is true of
-neither. An agent with no profile appears under the plain `Kiro` row.
+neither. An agent with no profile appears under the plain `Kiro` row. Codex works
+the same way: `Codex (<profile>)` rows next to the plain `Codex`.
 
 A profile that is configured but has never been logged in still gets a row,
 reading **Signed out — run `kiro-cli` to log in**. That is the reminder to go

package/dist/general-knowledge/skills/cross-instance-messaging/SKILL.md

@@ -7,11 +7,20 @@ roles: [general, worker]
 ## How to send
 
 Use fleet tools only (`send_to_instance`, `delegate_task`, `request_information`, `report_result`, `broadcast`):
-- Call returns immediately: `{ sent: true, queued: true }` — success, fleet owns delivery.
+- Call returns immediately: `{ sent: true, queued: true }` (plus `delivery_id` / `operation_id` for a durable send) — the fleet **accepted** it and owns delivery from here. Acceptance is not delivery.
 - **Do not wait** for the target to go idle; **do not** treat 30s IPC timeout as failure to re-send.
 - **Error only if the target does not exist** (or similar hard reject) — then fix the name, don't spam.
 - **Never re-send because the reply said `queued`** — that means the message is already queued.
 - Supplement/correction to work you just sent → `steer: true`; a new task → normal send.
+- A message body over 12 KiB is refused (`defaults.max_cross_instance_message_bytes`): put long content in a file and send its path.
+
+## Checking a delivery
+
+Only when a result is unclear: `delivery_status` with the `operation_id` / `delivery_id` / `correlation_id` you got.
+- `queued`, `delivering`, `retry_wait` — not handed over yet; the fleet keeps trying.
+- `submission_started`, `reconciliation_pending`, `uncertain` — it may already have arrived: **do not resend**.
+- `delivered` — the target received it (not necessarily processed it yet; `consumed_at` says when it did).
+- `failed`, `cancelled` — not delivered; fix the cause, then send again.
 
 ## requires_reply
 
@@ -21,7 +30,7 @@ Use fleet tools only (`send_to_instance`, `delegate_task`, `request_information`
 ## Task flow
 
 - Coordinator flow: `delegate_task` → silent work → `report_result` (zero ack-only pings).
-- Worker flow: finish with `report_result`, or use `request_information` when blocked. A normal worker must not call `delegate_task` or re-delegate work.
+- Worker flow: finish with `report_result`, or use `request_information` when blocked. Prefer `report_result` over delegating; use `delegate_task` only when your assignment allows it, and never re-delegate a task back to its sender.
 - Cross-instance traffic is `[from:name]` → answer with `send_to_instance` / `report_result`, never `reply`
 
 ## Before acting on a peer's message

package/dist/general-knowledge/skills/delegation-playbook/SKILL.md

@@ -6,11 +6,11 @@ roles: [general]
 
 ## Delegation Protocol
 
-Every delegation via send_to_instance() MUST include:
+Every delegation via `delegate_task` MUST include:
 
-1. Task scope — what exactly to do, bounded clearly
-2. Expected output — what to return and in what form
-3. Policy reminder — "Follow Development Workflow policy" (for code tasks)
+1. `task` — what exactly to do, bounded clearly
+2. `success_criteria` — what to return, in what form, and how it will be judged
+3. A policy reminder in `context` — "Follow Development Workflow policy" (for code tasks)
 
 ### Loop Prevention
 
@@ -29,11 +29,11 @@ When an instance reports back, classify the outcome:
 - Success → Summarize key results for user. Omit internal coordination noise.
 - Partial → State what succeeded, what remains, proposed next steps.
 - Failure → Retry up to 2 times. If still failing: try alternative instance, reduce scope, or return partial result clearly marked.
-- No response → Ping again after reasonable wait. If still silent: report to user with options.
+- No response → when a `[system:reply-overdue]` notice arrives (after 15 min by default), check `describe_instance` and `delivery_status` before asking again. If still silent: report to user with options.
 
 ## Shared Decisions
 
-Use post_decision() / list_decisions() for any choice that affects more than 1 instance, changes an API contract, introduces a new dependency, or alters deployment process.
+Use `post_decision` / `list_decisions` for any choice that affects more than 1 instance, changes an API contract, introduces a new dependency, or alters deployment process. The default `scope: "project"` reaches only instances in the same working directory — use `scope: "fleet"` for anything wider.
 
 When instances disagree, collect both viewpoints, make a decision, and record it via post_decision.
 
@@ -47,6 +47,6 @@ When instances disagree, collect both viewpoints, make a decision, and record it
 
 When users create specialized instances, suggest these configurations:
 
-- **Reviewer instances**: Add `pre_task_command: "/chat load reviewer-base"` to reset context before each review, preventing influence from previous conversations.
-- **Collab mode**: For multi-bot channels, use `/collab` to enable @mention-based triggering.
+- **Reviewer instances** (kiro): add `pre_task_command: "/chat load reviewer-base.json"` to reset context before each review. It is pasted before every message as-is, so on other backends use a command their CLI accepts.
+- **Collab mode**: For multi-bot channels, a channel admin's `/collab` lets other bots' and webhooks' messages reach the instance.
 - **Cost control**: Set per-instance `cost_guard` for expensive backends.

package/dist/general-knowledge/skills/fleet-config/SKILL.md

@@ -40,16 +40,16 @@ instances:
     backend: kiro-cli
     kiro_ui: legacy    # default — current stable behavior
     # kiro_ui: tui     # try the newer TUI
-    # kiro_ui: v3      # try the v3 profile
 ```
+`kiro_ui: v3` is refused by validation — do not set it.
 Leave unset (or `legacy`) unless testing a newer profile. Ignored by other backends.
 
 ## Reply completion guard
 
 `reply_completion_guard` detects a human-channel turn that ended without a
 delivered reply and asks the agent to send one bounded recovery reply. It is
-enabled by default for Claude Code in MCP mode and Kiro legacy/TUI in MCP mode.
-Kiro v3 is excluded because its turn-end signal is unverified. Codex and other
+enabled by default for Claude Code, Codex, Muse and Kiro legacy/TUI (it needs the
+MCP server). Kiro v3 is excluded because its turn-end signal is unverified. Other
 backends keep the setting but do not claim the protection is active.
 
 Prefer a narrow per-instance override when one worker repeatedly finishes work
@@ -79,14 +79,14 @@ it does not turn tool-call text into proof that the reply reached the channel.
 Fix all errors before `agend reload`; warnings are advisory.
 
 **Common fleet.yaml mistakes:**
-- Missing `channel.mode` field → error on start
+- `channel.mode` left out → it is `topic` (say so explicitly if you mean another mode)
 - Wrong indentation (YAML is indent-sensitive)
 - `topic_id` as string vs number (both work, but be consistent)
 - `backend` typo (valid: `claude-code`, `codex`, `opencode`, `kiro-cli`, `antigravity`, `grok`, `muse`); `gemini-cli` was removed in 2.1.12 — use `antigravity`
 - `model` using wrong format for the backend
 
 **Common classicBot.yaml mistakes:**
-- `allowed_guilds` values must be strings (Discord IDs are too large for YAML integers)
+- `allowed_guilds` values should be quoted strings: numbers are accepted, but a Discord ID above 2^53 loses digits as a YAML integer
 - Channel IDs as keys must be quoted strings
 - Missing `defaults` section (optional but recommended)
 

package/dist/general-knowledge/skills/fleet-health/SKILL.md

@@ -7,9 +7,9 @@ roles: [general]
 ## Check health
 
 Prefer the fleet tools — they already know each instance's state:
-- `get_fleet_status` — status + execution state (idle / working / stuck) for every instance.
-- `describe_instance("<name>")` — one instance's status, last activity, description.
-- `list_instances` — quick roster.
+- `list_instances` — every instance with its status and `instance_state`: idle / working / stuck / paused / awaiting_input (the CLI is waiting at an on-screen dialog or input).
+- `describe_instance("<name>")` — one instance's status, state, last activity, description.
+- `get_fleet_status` — just the counts: total, running, paused, stopped.
 
 The daemon derives idle/working/stuck itself (per-backend), so you do **not** need to
 scrape prompts. Don't hand-write pane-text checks like `X% !>` — that prompt is
@@ -20,7 +20,7 @@ kiro-specific and wrong for claude-code / codex / grok / antigravity.
 When the user wants the live screen (not just a status word):
 - `get_instance_logs("<name>")` — recent output (the raw terminal stream).
 - Raw terminal (last resort, no tool for the live pane):
-  `tmux capture-pane -t agend:<name> -e -p | tail -20` — keep `-e`: without it the screen's styling is lost.
+  `tmux capture-pane -t agend:<name> -e -p | tail -20` on the default AGEND_HOME (an isolated home uses session `agend-<hash>` on its own `-L` socket; `agend attach <name>` works in both) — keep `-e`: without it the screen's styling is lost.
 
 **Faint text is not input.** A CLI paints its own suggestion or placeholder in the input box
 exactly like typed text, only faint (Claude Code: `❯ Try "…"`, or a suggested next prompt).

package/dist/general-knowledge/skills/fleet-restart/SKILL.md

@@ -7,18 +7,23 @@ roles: [general]
 ## Fleet Restart & Recovery
 
 **Restart types:**
-- `agend fleet restart` — full stop + start (picks up new code after build & link)
+- `agend fleet restart` — graceful, in the same process: instances restart once idle (does **not** load new code)
+- `agend fleet restart --reload` — full process restart: new code and new connections take effect
+- `agend fleet restart <name>` — restart one instance now
 - `agend reload` — SIGHUP hot-reload, reconciles instances without restarting the fleet process
 - `restart_instance("<name>")` — single instance restart, reloads fleet.yaml first
+- `agend restart` — restarts the AgEnD service itself (systemd / launchd / detached), not one instance
+
+**From a fleet agent session**, `agend stop`, `agend restart`, `agend update`, `agend fleet stop` and `agend fleet restart` (without a name) affect every instance and are refused unless you pass `--yes`. Each is written to `restart-audit.log` first. `--force` is for an operator's own shell only.
 
 **After tmux crash:**
-- Fleet auto-detects tmux server death and triggers circuit breaker (30s pause)
+- Fleet detects the tmux server's death and opens a recovery window: spawns and deliveries are held 30 s, then 2 min and 10 min if it crashes again (losing single windows while the server lives holds nothing)
 - Some instances may fail to restart due to rate limits from simultaneous startup
 - Fix: manually restart failed instances, or do another `agend fleet restart`
 - Check failed instances: `agend ls` shows "stopped" status
 
 **Rate limit recovery:**
-- If you see "PTY error: Rate limit reached" or "crash loop — respawn paused", wait 1-2 minutes
+- If the log shows `PTY error: …rate limit…`, or the notice "crashed 3+ times shortly after launch — paused for recovery", wait 1-2 minutes
 - Then `restart_instance` the affected instance
 - Do NOT restart all instances simultaneously — this worsens rate limits
 
@@ -26,21 +31,16 @@ roles: [general]
 
 **Update AgEnD to latest version:**
 ```bash
-agend update              # update to latest
-agend update --version 2.1.0  # pin a specific version
+agend update --yes            # from a fleet session: the installed channel's latest (a beta stays on beta), then restart
+agend update --version 2.2.0 --yes  # a specific version
 ```
 
-The `agend update` command automatically:
-- Detects if sudo is needed (switches to nvm if so)
-- Installs new version
-- Verifies installation succeeded
-- Updates service file (ExecStart path)
-- Restarts fleet
+It installs the selected release, checks the install, and restarts the fleet service. `--alpha` / `--beta` / `--stable` pick a channel; details in docs/cli.md.
 
 **Manual restart (if update isn't needed):**
 ```bash
-agend fleet restart       # graceful restart (SIGUSR2) — keeps sessions, reloads config
-agend fleet stop && agend fleet start  # full restart — new code takes effect
+agend fleet restart --yes           # graceful (SIGUSR2) — keeps sessions, reloads config
+agend fleet restart --reload --yes  # full process restart — new code takes effect
 ```
 
 **NEVER do:**

package/dist/general-knowledge/skills/instance-lifecycle/SKILL.md

@@ -22,7 +22,8 @@ roles: [general]
 
 ## Monitoring state
 
-- `get_fleet_status` / `describe_instance("<name>")` — status + idle/working/stuck + last
-  activity (the daemon derives the state; don't scrape pane prompts).
+- `describe_instance("<name>")` / `list_instances` — status + `instance_state` (idle / working /
+  stuck / paused / awaiting_input) + last activity (the daemon derives the state; don't scrape pane
+  prompts). `get_fleet_status` only counts running / paused / stopped.
 - For the raw screen, see the fleet-health skill (`get_instance_logs` / tmux capture), including
   why faint text in another instance's input box is a CLI suggestion, not the operator's input.

package/dist/general-knowledge/skills/kiro-engine-migration/SKILL.md

@@ -54,3 +54,9 @@ The user has already been shown the plain notice in this topic. When they ask, e
   conversation, and the move cannot be undone.
 - Never run `kiro-cli` yourself, and never delete or edit anything under `~/.kiro` or kiro's data directory.
 - Never reply to the `[system:kiro-incompat]` notice itself. It is information, not a request.
+
+## One kiro agent per instance (#906)
+
+Since kiro-cli 2.21, each AgEnD kiro instance (tui / v2 engine) runs as its own kiro agent, holding only its own
+AgEnD MCP server and instructions, and resumes its own conversation by id — instances sharing a working directory
+no longer see each other's tools. Legacy (`kiro_ui: legacy`) launches are unchanged.

package/dist/general-knowledge/skills/model-discovery/SKILL.md

@@ -21,16 +21,16 @@ capability (cheap/fast vs deep reasoning), or the backend needs one to behave
 | Backend | Omit `model` means | Notes |
 |---|---|---|
 | kiro-cli | account default | **`model: auto`** lets kiro pick per turn — usually what you want |
-| claude-code | account default | ids are aliases: `sonnet`, `opus`, `haiku`, `opusplan`, `default` |
+| claude-code | account default | ids are aliases: `sonnet`, `opus`, `haiku`, `opusplan`, `default`, `Fable`; `list_models` also offers the account's full ids (with `[1m]` variants) |
 | codex | account default | |
 | grok | account default | |
 | antigravity | account default | |
-| opencode | provider default | ids are **`provider/model`**, e.g. `opencode/big-pickle` |
+| opencode | provider default | ids are **`provider/model`**, as `opencode models` prints them |
 
 ## Discover real names
 
-**Use the `list_models` tool** — it reads the fleet's probe cache (refreshed every
-24h) and falls back to a live probe:
+**Use the `list_models` tool** — it reads the fleet's probe cache (re-probed when
+older than 1 h; never used past 24 h) and falls back to a live probe:
 
 - `list_models({ backend: "kiro-cli" })` → the account catalog
 - `list_models({ instance_name: "x" })` → read through **that instance's** config
@@ -47,11 +47,11 @@ Underlying commands, if you need them by hand:
 
 | Backend | Command |
 |---|---|
-| kiro-cli | `kiro-cli --list-models` |
+| kiro-cli | `kiro-cli chat --list-models --format json` |
 | grok | `grok models` |
 | opencode | `opencode models` |
 | antigravity | `agy models` |
-| codex | **no command** — the CLI writes `models_cache.json` in its CODEX_HOME |
+| codex | `codex debug models` (with its CODEX_HOME set) — refreshes `models_cache.json` when it is older than a few minutes |
 | claude-code | fixed alias set (no command) |
 
 ## Setting one on create_instance
@@ -65,9 +65,9 @@ Underlying commands, if you need them by hand:
 ## Two traps
 
 **antigravity: keep the effort suffix.** The suffix is part of the selectable id,
-not decoration — `gemini-3.6-flash-medium` and `gemini-3.6-flash-low` are
-different models. Take the id from `list_models`, not the display label the TUI
-shows (`Gemini 3.5 Flash (Medium)`).
+not decoration — the same model at two effort levels is two different ids. Take
+the id from `list_models` (e.g. `gemini-3.6-flash-high`), not the display label
+the TUI shows.
 
 **Pass-through: AgEnD does not gate model names.** An unknown id is warned about,
 then handed to the CLI anyway. So a name missing from `list_models` may still be

package/dist/general-knowledge/skills/multi-channel/SKILL.md

@@ -55,11 +55,17 @@ The `channel_id` field explicitly binds a general to an adapter. Without it, mat
 |---------|---------|-----|
 | One general for two platforms | TG messages reply in DC | Add a second general with `channel_id` |
 | `channels:` without unique `id` per entry | Adapter collision | Set `id: discord` / `id: telegram` |
-| Using `channel:` (singular) for multi-platform | Second platform ignored | Switch to `channels:` array |
+| Using `channel:` (singular) for multi-platform | Second platform ignored | Switch to `channels:` array (`channel:` is deprecated; the validator warns when both are set) |
+
+## Web chat
+
+The dashboard's web chat is one more way in, not a `channels:` entry: its messages reach an instance as
+`[user:… via web, …]` and are answered with `reply` like any other. By default each is also copied to the
+instance's own topic (`web.echo_to_channel: false` turns that off; ClassicBot rooms only with `web_echo: true`).
 
 ## Single → Multi Migration
 
 1. Change `channel:` to `channels:` array, add `id` to existing entry
 2. Add new platform entry with its own `id`
 3. Add a general instance for the new platform with `channel_id: <new-adapter-id>`
-4. Restart fleet: `agend fleet restart`
+4. Restart the whole process — connections are created when it starts: `agend fleet restart --reload` (`--yes` from a fleet session)

package/dist/general-knowledge/skills/scheduling/SKILL.md

@@ -8,15 +8,17 @@ roles: [general, worker]
 
 - `create_schedule` — make a schedule (recurring or one-shot).
 - `list_schedules` — list all (optionally filter by target instance).
-- `update_schedule` — change cron/at/message/timezone/enabled of an existing one.
+- `update_schedule` — change cron/at/message/target/label/timezone/enabled of an existing one.
 - `delete_schedule` — remove one.
 
 A schedule injects `message` into the `target` instance when it fires
-(`target` defaults to the current instance).
+(`target` defaults to the current instance). With the worker or standard tool set you may
+manage only schedules that target you and that you created; for anything else ask the
+coordinator with `report_result`.
 
 ## Three ways to schedule
 
-**1. Recurring (cron)** — `cron` + optional `timezone` (IANA, default `Asia/Taipei`):
+**1. Recurring (cron)** — `cron` + optional `timezone` (IANA; default the fleet's `defaults.scheduler.default_timezone`, `Asia/Taipei` unless set):
 ```
 create_schedule({ cron: "0 9 * * *", message: "Daily standup summary", timezone: "Asia/Taipei" })
 ```

package/dist/general-knowledge/skills/session-management/SKILL.md

@@ -8,7 +8,8 @@ roles: [general]
 
 When AgEnD sees `auth_error` it **pauses** that instance (`pausePending` sticky):
 - One notification **per backend** (not per instance) — log in once, same-backend peers recover.
-- Auth is **per-user global** across backends: claude-code, codex, kiro, grok, opencode, antigravity.
+- Auth is **per backend**: one re-login restores every instance on that backend (claude-code, codex, kiro-cli, grok, opencode, antigravity, muse).
+- Re-login: `/login <backend>` (opencode: `opencode auth login` in a terminal), then wake the affected instance.
 - Messages while paused stay in the **queue** — do not re-send.
 - After the user re-auths: `wake` / normal wake clears `pausePending`.
 
@@ -24,7 +25,7 @@ Verified by running each one, not read from docs.
 | **codex** | ⚠️ no index — parse rollout files | ✅ `codex exec resume <id>` | ❌ must parse the rollout |
 | **antigravity** | ❌ index covers ~23%, 2 months stale | ✅ `agy --conversation <id>` | ⚠️ `title` empty, use `preview` |
 
-**Restoring a specific session is a manual operator action, not an AgEnD feature.** AgEnD always launches a backend on its *most recent* session (`--continue` / `--last` / `--resume`). To reach any other session someone must drive the pane or the CLI by hand.
+**Restoring a specific session is a manual operator action, not an AgEnD feature.** AgEnD launches each backend on the instance's own session: codex `resume <id>` (the thread for this exact directory; `--last` only as a fallback when the session DB is unreadable and no other codex instance shares the repository), grok `--resume <id>`, kiro its own conversation id, claude-code `--continue` (only when the instance has a `session-id` marker and the directory has a Claude transcript). To reach any other session someone must drive the pane or the CLI by hand.
 
 **kiro is the exception worth knowing:** its export → `/chat load` works on a **live, idle instance** with no restart. Every other backend needs the instance stopped (or the CLI run manually) because the session is chosen by a launch flag.
 
@@ -118,7 +119,7 @@ grep -h '"type":"ai-title"' <file>.jsonl | tail -1
 ```
 A session with no `ai-title` line is simply untitled — say so rather than inventing a label.
 
-**Restore:** `claude -r <session-id>` (or `claude --resume` for a picker that accepts a search term). `-c` / `--continue` takes the most recent for the cwd — that is what AgEnD launches with.
+**Restore:** `claude -r <session-id>` (or `claude --resume` for a picker that accepts a search term). `-c` / `--continue` takes the most recent for the cwd — AgEnD launches with it only when the instance has a `session-id` marker and the cwd has a Claude transcript.
 
 > ⚠️ **Check the ID exists before using it.** AgEnD guards `--continue` precisely because resuming a session that isn't there sends claude into a restart loop. Confirm the `<id>.jsonl` file is present in the encoded project dir first.
 
@@ -150,7 +151,7 @@ for ts, sid in sorted(out, reverse=True):
 ```
 It opens many files, but only one line each, so it stays cheap.
 
-**Restore:** `codex exec resume <session-id> "<prompt>"` non-interactively, or `codex resume <session-id>` for the TUI (bare `codex resume` opens a picker). `codex resume --last` is what AgEnD launches with. The ID argument also accepts a session *name*.
+**Restore:** `codex exec resume <session-id> "<prompt>"` non-interactively, or `codex resume <session-id>` for the TUI (bare `codex resume` opens a picker). AgEnD launches `codex resume <id>` with the thread recorded for this exact directory; `codex resume --last` is only its fallback (an unreadable session DB, no other codex instance in the repository). The ID argument also accepts a session *name*.
 
 **Summary:** ❌ none available without parsing. `session_meta` carries only id/cwd/timestamp; to describe a session you must read further `event_msg` lines. Tell the user the timestamp and let them pick, rather than guessing at a topic.
 
@@ -186,6 +187,6 @@ cur.execute("SELECT conversation_id, preview, step_count, last_modified_time "
 ## Fork (source must be idle)
 
 - **kiro:** `/chat save name.json -f` → `create_instance` → copy workspace file → `/chat load name.json`
-- **claude-code:** copy the newest `*.jsonl` into the target's encoded project dir → start (uses `--continue`)
+- **claude-code:** copy the newest `*.jsonl` into the target's encoded project dir → start (AgEnD adds `--continue` only if the target's instance dir also has its `session-id` marker)
 - **grok:** `/fork` inside the TUI branches the conversation into a peer session
 - Prefer `replace_instance` when the whole session is poisoned (see instance-lifecycle)

package/dist/general-knowledge/skills/tui-effort/SKILL.md

@@ -18,8 +18,8 @@ instances:
 ```
 
 **kiro_ui 模式差異：**
-- `kiro_ui: tui`：Kiro v2 TUI（預設推薦）；本 skill 適用。
-- `kiro_ui: v3`：v3 unified agent harness；是不同的 agent engine，不只是換皮膚。session 格式與 v2 不相容，不能互 resume。若要使用 v3，需另外實測 `/effort` 行為。
+- `kiro_ui: tui`：Kiro v2 TUI（需明確設定；預設是 `legacy`）；本 skill 適用。
+- `kiro_ui: v3`：目前會被設定驗證拒絕，不要設定。
 - `kiro_ui: legacy`：舊 UI，互動行為不同，本 skill 不適用。
 
 若修改 `kiro_ui`，先 reload 再 restart：

package/dist/general-knowledge/skills/worker-collaboration/SKILL.md

@@ -11,9 +11,10 @@ roles: [worker]
 - Treat the assignment as the full scope unless the sender explicitly expands it.
 - Work without acknowledgment-only messages. Silence means the task is in progress.
 - Fleet orchestration is not yours: you do not have `create_instance`,
-  `delete_instance`, `restart_instance`, `deploy_template`, the team tools, or
-  the tools that create, change or delete schedules. Calling one is refused
-  with an explanation rather than silently ignored. If the work needs more
+  `delete_instance`, `restart_instance`, `deploy_template` or the team tools,
+  and the schedule tools reach only schedules that target you and that you
+  created. Anything else is refused with an explanation rather than silently
+  ignored. If the work needs more
   capacity or another agent restarted, say so with `report_result` and let the
   coordinator decide.
 - You can still *look*: `list_schedules`, `list_deployments`, `list_instances`

package/dist/general-knowledge/steering/core-rules.md

@@ -8,7 +8,7 @@ When creating a new instance with `create_instance`:
 
 **Pre-checks (mandatory):**
 1. **Check for duplicate working directory** — Run `list_instances` and verify no existing instance uses the same `working_directory`. Two instances sharing a directory causes file conflicts and race conditions.
-2. **Verify the directory exists** — If specifying a directory, confirm it exists on disk before calling create.
+2. **Verify the directory exists** — If specifying a directory, confirm it exists on disk before calling create. When the fleet sets `project_roots`, it must also be inside one of them, or create is refused.
 3. **Use unique names** — The instance name is derived from `topic_name` or `basename(directory)`. Avoid generic names like "dev" or "test" that may collide.
 
 **Post-checks (mandatory):**
@@ -23,12 +23,13 @@ When creating a new instance with `create_instance`:
 ## What NOT to Do (Dangerous Operations)
 
 - **Don't delete `~/.agend/fleet.yaml`** while fleet is running
-- **Don't delete `~/.agend/fleet.pid`** manually — use `agend fleet stop`
+- **Don't delete `~/.agend/fleet.pid`** manually — use `agend fleet stop` (from a fleet session it needs `--yes`, and it stops every instance)
 - **Don't kill tmux server** (`tmux kill-server`) — kills all agent sessions
 - **Don't edit instance output.log** — it's actively written by the daemon
 - **Don't run two fleet processes** on the same AGEND_HOME — port/socket conflicts
 - **Don't change `channel.group_id`** without re-creating all topics — routing breaks
 - **Don't remove an instance from fleet.yaml** that has active work — stop it first
+- **Don't try to get around a Settings confirmation** — a sensitive change made in the web Settings (access, secrets, connections, …) waits for a fleet admin to confirm it in General, or with `agend settings confirm <id>` on the host
 
 ## Access Mode Reference
 
@@ -37,7 +38,7 @@ fleet.yaml `channel.access.mode` valid values:
 | Mode | Behavior |
 |------|----------|
 | `locked` | Only `allowed_users` can interact (default) |
-| `pairing` | Users can request access via `/pair` command |
+| `pairing` | A user sends `/pair` (Telegram), gets a code, and the owner grants access |
 | `open` | All users can interact, no restrictions |
 
 Example:
@@ -46,7 +47,7 @@ channel:
   access:
     mode: open          # everyone can use
     # mode: locked      # whitelist only (add allowed_users)
-    # mode: pairing     # users self-register via /pair
+    # mode: pairing     # /pair gives a code the owner approves
     allowed_users: [123456789]  # only needed for locked/pairing
 ```
 
@@ -72,14 +73,14 @@ Always use a dedicated subdirectory like `/home/user/projects/my-project` or let
 Use layered memory to minimize context usage:
 
 1. **Fleet Decision** — short, shared rules only (role, workflow rules, TODOs). Keep concise (~20 lines guideline). If it exceeds this, consider whether the details belong in soul.md instead.
-2. **soul.md** (workspace root) — full memory: architecture, decisions, history. Loaded as steering.
+2. **soul.md** (workspace root) — full memory: architecture, decisions, history. AgEnD does not load it for you: read it when you need it.
    - If soul.md doesn't exist, do NOT create one unprompted. Only create when the user explicitly asks.
-3. **Skills** (`.kiro/skills/`) — reusable workflows. On-demand loading.
+3. **Skills** — reusable workflows, loaded on demand, in your backend's skills directory: `.kiro/skills/` (kiro), `.claude/skills/` (claude-code), `.agents/skills/` (codex, opencode, muse, antigravity), `.grok/skills/` (grok).
 
 Rules:
 - Keep Fleet Decisions minimal. Move details to soul.md.
 - Each instance maintains its own soul.md (not shared).
-- Good workflows → **propose** converting to a skill. Create in `.kiro/skills/<name>/SKILL.md` only after user approval.
+- Good workflows → **propose** converting to a skill. Create `<skills directory>/<name>/SKILL.md` (see Skills above) only after user approval.
 - Global skills (`src/general-knowledge/skills/`) only for knowledge ALL instances need.
 - Never put architecture details or bug history in Fleet Decisions.
 - After completing a **multi-step task that introduced new architectural knowledge or a reusable process**, suggest updating soul.md. Do NOT ask after routine tasks (reviews, single-file fixes, Q&A).

package/dist/instance-avatar.d.ts

@@ -0,0 +1,36 @@
+export type AvatarDescriptor = {
+    kind: "image";
+    src: string;
+} | {
+    kind: "emoji";
+    text: string;
+} | {
+    kind: "emoji";
+    src: string;
+    alt: string;
+} | {
+    kind: "initial";
+    text: string;
+};
+/** The first user-perceived character, upper-cased where that means anything ("é" → "É", "中" stays). */
+export declare function firstCharacter(text: string): string;
+export declare function avatarFor(input: {
+    name: string;
+    displayName?: string | null;
+    /** The profile picture's version, when one is uploaded (step 0). */
+    profileVersion?: string | null;
+    /** The bot's avatar: its connection id and cached version, when the instance has its own bot and the avatar is on disk. */
+    bot?: {
+        connection: string;
+        version: string;
+    } | null;
+    /** The instance's own `status_emojis.delivered`, as configured. */
+    personaEmoji?: unknown;
+}): AvatarDescriptor;
+/**
+ * The connections that are ONE instance's own bot: not the primary (that is the fleet's shared bot), and answering for
+ * exactly one instance or ClassicBot room. `assignments` is every instance and room with the connection it uses.
+ */
+export declare function ownBotConnections(primary: string | undefined, assignments: ReadonlyArray<readonly [instance: string, connection: string | undefined]>): Map<string, string>;
+/** A Discord role colour as the page may use it: `#rrggbb`, never black (Discord's "no colour"). */
+export declare function accentColor(raw: unknown): string | null;

package/dist/instance-avatar.js

@@ -0,0 +1,57 @@
+/**
+ * #1630 (design: the comment on #1630): what stands for an instance in the web app — decided here, on the server,
+ * once; the page only draws it. In order:
+ *   0. the picture uploaded for it in View (its profile avatar);
+ *   1. its own bot's avatar — only when it has a bot of its own: an instance on the shared bot skips this, the same
+ *      face for everyone tells nobody apart; so does a bot with no avatar set (a default avatar says nothing);
+ *   2. its persona emoji (`status_emojis.delivered`, what set_persona_emoji sets): unicode as text, a Discord server
+ *      emoji through the emoji route (a Telegram custom emoji has no picture here and falls through);
+ *   3. the first character of its display name, or of its name.
+ * Images are same-origin `/ui/img/…` URLs only; the version makes a changed picture a new URL.
+ */
+import { normalizeEmoji } from "./status-emojis.js";
+const GRAPHEMES = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+/** The first user-perceived character, upper-cased where that means anything ("é" → "É", "中" stays). */
+export function firstCharacter(text) {
+    for (const { segment } of GRAPHEMES.segment(text.trim()))
+        return segment.toLocaleUpperCase();
+    return "?";
+}
+export function avatarFor(input) {
+    if (input.profileVersion)
+        return { kind: "image", src: `/ui/img/avatar/${encodeURIComponent(input.name)}?v=${encodeURIComponent(input.profileVersion)}` };
+    if (input.bot)
+        return { kind: "image", src: `/ui/img/bot/${encodeURIComponent(input.bot.connection)}?v=${encodeURIComponent(input.bot.version)}` };
+    const emoji = normalizeEmoji(input.personaEmoji);
+    if (emoji?.kind === "unicode")
+        return { kind: "emoji", text: emoji.value };
+    if (emoji?.kind === "custom")
+        return { kind: "emoji", src: `/ui/img/emoji/${emoji.id}`, alt: `:${emoji.name}:` };
+    return { kind: "initial", text: firstCharacter(input.displayName || input.name) };
+}
+/**
+ * The connections that are ONE instance's own bot: not the primary (that is the fleet's shared bot), and answering for
+ * exactly one instance or ClassicBot room. `assignments` is every instance and room with the connection it uses.
+ */
+export function ownBotConnections(primary, assignments) {
+    const users = new Map();
+    for (const [instance, connection] of assignments) {
+        if (!connection)
+            continue;
+        const list = users.get(connection);
+        if (list)
+            list.push(instance);
+        else
+            users.set(connection, [instance]);
+    }
+    const own = new Map(); // instance → its own connection
+    for (const [connection, instances] of users)
+        if (connection !== primary && instances.length === 1)
+            own.set(instances[0], connection);
+    return own;
+}
+/** A Discord role colour as the page may use it: `#rrggbb`, never black (Discord's "no colour"). */
+export function accentColor(raw) {
+    return typeof raw === "string" && /^#[0-9a-f]{6}$/i.test(raw) && raw.toLowerCase() !== "#000000" ? raw.toLowerCase() : null;
+}
+//# sourceMappingURL=instance-avatar.js.map

package/dist/instance-avatar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-avatar.js","sourceRoot":"","sources":["../src/instance-avatar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAQpD,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC,CAAC;AAC7E,wGAAwG;AACxG,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,KAAK,MAAM,EAAE,OAAO,EAAE,IAAI,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAAE,OAAO,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAC7F,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,KASzB;IACC,IAAI,KAAK,CAAC,cAAc;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,kBAAkB,kBAAkB,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,kBAAkB,CAAC,KAAK,CAAC,cAAc,CAAC,EAAE,EAAE,CAAC;IAC1J,IAAI,KAAK,CAAC,GAAG;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,eAAe,kBAAkB,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,kBAAkB,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC;IACnJ,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IACjD,IAAI,KAAK,EAAE,IAAI,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;IAC3E,IAAI,KAAK,EAAE,IAAI,KAAK,QAAQ;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB,KAAK,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,KAAK,CAAC,IAAI,GAAG,EAAE,CAAC;IACjH,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,cAAc,CAAC,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;AACpF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAA2B,EAAE,WAAuF;IACpJ,MAAM,KAAK,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC1C,KAAK,MAAM,CAAC,QAAQ,EAAE,UAAU,CAAC,IAAI,WAAW,EAAE,CAAC;QACjD,IAAI,CAAC,UAAU;YAAE,SAAS;QAC1B,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACnC,IAAI,IAAI;YAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;;YAAM,KAAK,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;IACxE,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAkB,CAAC,CAAU,gCAAgC;IAChF,KAAK,MAAM,CAAC,UAAU,EAAE,SAAS,CAAC,IAAI,KAAK;QAAE,IAAI,UAAU,KAAK,OAAO,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;YAAE,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAE,EAAE,UAAU,CAAC,CAAC;IACtI,OAAO,GAAG,CAAC;AACb,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,WAAW,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC9H,CAAC"}

package/dist/instance-config-impact.js

@@ -82,6 +82,11 @@ const FLEET_FIELD_IMPACTS = {
     "web.public_link.allow_public": "now",
     "web.public_link.ttl_minutes": "now",
     "web.public_link.protocol": "now",
+    // #1620: read at every session check, and by /login when it starts a terminal.
+    "web.session.local.absolute_hours": "now",
+    "web.session.local.idle_hours": "now",
+    "web_terminal.enabled": "now",
+    "web_terminal.ttl_minutes": "now",
     "defaults.locale": "now",
     "fleet.channels": "fleet",
     "fleet.channel.access.mode": "fleet",