@songsid/agend 2.3.4-beta.7 → 2.3.4-beta.9

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

@@ -0,0 +1,390 @@
+---
+name: concepts
+description: AgEnD product concepts and definitions — fleet, instances, General, tool sets, delivery, schedules, and the rest; the agents' built-in role reference
+roles: [general, worker]
+---
+
+# AgEnD concepts and definitions
+
+Draft. Each term states what the code on main does today, verified against the
+listed files. Anything inferred is marked. These definitions were approved by the project
+owner; behaviour that differs from them is a bug or needs a decision.
+Where code and a decision disagree, see Mismatches at the end. Fleet decisions are scoped to the leader's project root and cannot be
+opened by readers, so each citation carries its user-facing summary inline.
+
+## fleet
+
+The whole multi-agent system on one host: its instances, schedules, teams,
+decisions and task board, driven by one daemon from one `fleet.yaml` in one
+AgEnD home (`~/.agend`).
+
+- Can: run agents reachable from chat connections, the web dashboard, or both.
+- Can't: span hosts. There is one daemon, one fleet process, one home dir.
+- Code: `src/fleet-manager.ts` (`FleetManager`), `src/config.ts` (`FleetConfig`).
+- Refs: —
+
+## instance / agent
+
+One agent is one instance: a daemon driving one CLI in its own tmux pane, with
+its own transcript, topic or room, and tool set. `instance` is the config and
+runtime word (`fleet.yaml` `instances`); `agent` is the everyday word.
+
+- Can: chat and call MCP tools within its tool set; message peers with
+  `send_to_instance`, `delegate_task`, `report_result`.
+- Can't: exceed its tool set, or touch another instance's state except through
+  fleet tools (same-OS-user processes are not isolated from each other —
+  see `docs/design/coordinator-tool-perms.zh-TW.md`).
+- Code: `src/daemon.ts`, `src/instance-lifecycle.ts`.
+- Refs: #804.
+
+## General
+
+The user's definition (fleet decision 9e3bea6c, "General is the AgEnD
+administrator", user 2026-11-04): as of beta.8 the `general` tool profile gets
+the full ORCHESTRATION set — instance create, delete, replace, start, stop,
+pause, wake and restart; templates; teams; `update_fleet_defaults`;
+`update_instance_config`; the kiro migrate and reconcile tools;
+`update_decision`; web settings — with no extra confirmation. The existing
+confirmations stay: sensitive config (tokens and access) is confirmed by a
+fleet admin, and #804 still refuses `tool_set` or `skipPermissions` escalation.
+It supersedes the 2026-09-21 "dispatcher" rationale and lands in beta.8 (agy's
+PR). General is the fleet's admin instance — the first agent on a new fleet —
+and owns the General topic. An instance runs under the `general` tool set when
+`general_topic: true` or its name is `general`.
+
+- Can (as of beta.8): everything in the worker profile plus the full
+  ORCHESTRATION set, delegation, schedules, and the user's web-appearance
+  settings.
+- Can't: exceed that set. Note the code on main is pre-beta.8 and still shows
+  the smaller subset (`src/tool-permissions.ts:107-136` holds only
+  `create/start/restart/wake_instance` plus the web settings
+  (`get/set_web_settings`) of the orchestration verbs) — expected
+  to change when beta.8 lands; see Mismatches.
+- Code: `src/tool-permissions.ts:107-136`, `:201-208`;
+  `src/instance-lifecycle.ts:2741` (the General instance cannot be replaced).
+- Refs: fleet decision 9e3bea6c.
+
+## `coordinator` tool set
+
+`TOOL_PROFILES.coordinator = WORKER + ORCHESTRATION`: every worker ability plus
+every verb that runs the fleet rather than does the work — for an agent that
+runs part of the fleet.
+
+- Can: create/delete/replace/start/stop/pause/wake/restart instances, manage
+  teams and templates, edit fleet defaults and instance config, run kiro
+  migration/reconciliation, change others' decisions and web settings
+  (`src/tool-permissions.ts:80-93`).
+- Can't: exceed the table — anything not listed is refused, with the reason
+  naming what the instance runs under.
+- Code: `src/tool-permissions.ts:100-107`.
+- Refs: `docs/design/coordinator-tool-perms.zh-TW.md` (zh-TW only).
+
+## worker
+
+An instance doing the work under the `worker` profile — the default when no
+`tool_set` is written (`resolveToolSet`, `src/tool-permissions.ts:201-208`).
+
+- Can: talk to people, report to peers (`send_to_instance`, `report_result`,
+  `request_information`, `broadcast`, `delegate_task`, `delivery_status`),
+  read fleet state, run its own task cards and schedules, keep its own theme
+  and Office character.
+- Can't: any orchestration verb. A refused call names the coordinator and
+  suggests reporting back instead (`src/tool-permissions.ts:357-374`).
+- Code: `src/tool-permissions.ts:33-72` (`WORKER`), `:185-208`.
+- Refs: #804, #895 (own schedules only).
+
+## team and team leader
+
+A team is a named group of instances (`fleet.yaml` `teams`) for targeted
+broadcasts and display grouping. A team leader is an instance that runs a
+team, given the `coordinator` (or `full`) tool set — a convention, not a
+separate role in code (approved by the user 2026-11-04).
+
+- Can: address several instances at once; group the sidebar and Office.
+- Can't: confer any authority — no leader election, no extra tools.
+- Code: `create_team`, `list_teams`, `update_team`, `delete_team`
+  (`src/channel/mcp-tools.ts`).
+- Refs: —
+
+## topic / General topic
+
+A topic is the chat home of one instance: a Telegram forum topic (or the
+equivalent scope on another connection) bound to it. The General topic is the
+General instance's topic. Commands that belong to General answer "works in the
+General topic" anywhere else.
+
+- Can: reach exactly that instance by talking there.
+- Can't: run General-only commands from another topic.
+- Code: `src/topic-commands.ts:836-839` (a General command typed in an
+  instance topic points to General, never to that agent);
+  `src/locale.ts:880` ("works in the General topic");
+  `src/tool-permissions.ts:207`.
+- Refs: —
+
+## Classic (ClassicBot) room
+
+A private chat or group where ClassicBot runs a single agent, managed by
+`classicBot.yaml` — separate from fleet topics, with its own admins
+(`defaults.admin_users`) and chat allowlists.
+
+- Can: `/start` an agent in the room and chat with it.
+- Can't: use fleet-topic commands or see the fleet; an unregistered chat stays
+  silent unless `/start` is allowed.
+- Code: `src/classic-channel-manager.ts`.
+- Refs: `docs/permissions.md`.
+
+## web-only fleet
+
+A fleet with no Discord or Telegram connection at all, used from the web
+dashboard (user decision, 2026-11-01/02). Its agents run in topic mode, so they
+can still message each other from the dashboard.
+
+- Can: everything chat fleets do, through `/ui` instead of chat.
+- Can't: chat ingress; `/web revoke` (there is no `/web`) — its Notice names
+  the host's way, signing every browser out.
+- Code: `src/web-only-fleet.ts:10-22`; `src/fleet-manager.ts:7807-7808`.
+- Refs: 28c2d3a3.
+
+## host owner / operator
+
+The person on the AgEnD computer. On a web-only fleet, the `agend web --code`
+session on this computer (`HOST_OPERATOR`): it confirms its own authority and
+answers its own prompts.
+
+- Can: confirm web authority, sign in, approve what asks for the host operator.
+- Can't: act as operator from another machine, or after the session was
+  revoked or ran out.
+- Code: `src/authority/web-authority.ts` (`HOST_OPERATOR`);
+  `src/fleet-manager.ts:2056-2060`; `src/locale.ts:1505-1506`.
+- Refs: 28c2d3a3.
+
+## fleet admin (`admin_users`)
+
+A platform user id listed in a channel's `access.allowed_users` (fleet), or in
+`defaults.admin_users` / `allowed_users` (ClassicBot). Admin is granted per
+person, never per instance. Fleet admin = the people; General = the
+administrator agent that carries out admin work for whoever may talk to it in
+the General topic (approved by the user 2026-11-04).
+
+- Can: admin-gated commands, confirming sensitive changes, managing access.
+- Can't: anything while unlisted — an empty list grants nobody, and open
+  access or pairing approval alone does not grant the role
+  (`docs/SECURITY.md:13`).
+- Code: `src/config-validator.ts:368-376`, `:677`.
+- Refs: —
+
+## guest (web)
+
+A person who is not a fleet admin, signed in on the dashboard with a guest
+code (`web.guests`, #1920). Guests see only the agents they are granted, in
+chat they could already use.
+
+- Can: chat with granted agents; sign out with `/web revoke` (own sessions).
+- Can't: admin routes, Notices, the usage report, or anything over surfaces
+  the fleet closed to guests.
+- Code: `src/config-validator.ts:738-740`.
+- Refs: #1920.
+
+## tool set / tool profile (`full`, `coordinator`, `general`, `worker`, `standard`, `minimal`)
+
+The server-side table that decides which MCP tools an instance may call
+(`TOOL_PROFILES`, `src/tool-permissions.ts:103-155`). `defaults.tool_set`
+applies to every instance without its own value, including General; an
+explicit `tool_set` always wins, otherwise the General instance gets `general`
+and everything else defaults to `worker` (`resolveToolSet`, `:201-208`).
+
+- `full`: every tool. Set explicitly only; nothing resolves to it by default
+  (the env-only fallback excepted, `:212-222`).
+- `coordinator`: worker abilities plus all orchestration verbs — the profile
+  for running the fleet.
+- `general`: General's administrator profile — as of beta.8, worker plus
+  every orchestration verb (fleet decision 9e3bea6c); before beta.8 only
+  `create/start/restart/wake_instance` — and the user's web settings.
+- `worker`: the default. Doing the work, with reporting (`report_result`)
+  that `standard` lacks.
+- `standard`: broad read access plus own schedules and themes, but no
+  `report_result`, `delegate_task` or `request_information` — so it cannot
+  complete the delegate → work → report protocol.
+- `minimal`: a narrow sender — reply, forward, check delivery, read decisions,
+  download, and see emoji/sticker listings.
+- Code: `src/tool-permissions.ts:30-155`.
+- Refs: #804.
+
+## Needs you
+
+The dashboard's `/ui/needs` queue plus the `needs_you` config: items parked
+for a person — permission prompts, usage-limit holds, dialogs the agent must
+not answer, unconfirmed deliveries.
+
+- Can: be acknowledged per item.
+- Can't: be answered by an agent on the person's behalf.
+- Code: `src/config.ts:284-293`; `src/web-api.ts` (`/ui/needs/ack`);
+  `src/daemon.ts:1564`, `:2071`, `:9888`.
+- Refs: —
+
+## Notices
+
+On a web-only fleet, the Notices feed (`/ui/notices`) — what General would
+have said in chat, kept, pushed and listed. Admins only, never a guest.
+
+- Can: be listed and marked seen.
+- Can't: be read by guests; on a chat fleet the feed is null because General
+  says them.
+- Code: `src/web-api.ts:2346-2349`; `src/fleet-manager.ts:7807-7808`.
+- Refs: #2910 D2.
+
+## delivery: ✅ 👀 ❌, "uncertain", queued hand-off (#3030)
+
+A channel message's status reactions, driven by the delivering daemon:
+⏳ queued (CLI busy, waiting), 👀 delivered (pasted + Enter, the agent has it),
+✅ confirmed (processing observed, or a native queue hand-off succeeded),
+❌ failed (window gone, retries exhausted). Cross-instance rows add two
+states: `uncertain` — the evidence was inconclusive, so never resend and never
+forward it as consent; and the queued hand-off (#3030) — a message handed to a
+backend-native queue, watched in the transcript and settled ✅ when a turn
+takes it, ❌ when it never does.
+
+- Can: tell the sender, at a glance, how far a message got.
+- Can't: prove permission. A receipt proves the CLI accepted the bytes, not
+  that the person authorized the act — verify the human receipt before anything
+  irreversible.
+- Code: `src/daemon.ts:7907-7913`; `:2450-2545`; `docs/delivery-verification.md`.
+- Refs: #3030, 7244b130, 954e5e96.
+
+## schedule
+
+A fleet timer: a cron line or a one-shot datetime that injects a message into
+an instance (`create_schedule`, `list_schedules`, `update_schedule`,
+`delete_schedule`). A non-coordinator's schedules may only target itself and
+must be created by itself; acting on other instances' schedules takes the
+`full`, `coordinator` or `general` profile.
+
+- Can: wake an instance with a message on a timetable.
+- Can't: reach beyond its scope — the target, not the tool, is the control.
+- Code: `src/channel/mcp-tools.ts` (schedule tools);
+  `src/tool-permissions.ts:67`, `:382`.
+- Refs: #895.
+
+## task board card
+
+A unit of tracked work. Main tasks `M-n` are outcomes; sub tasks `S-n` are
+steps under a main task. States: open, claimed, review, done, blocked,
+cancelled. A main task that waits for someone's confirmation goes to review;
+finishing it from review with done.
+
+- Can: carry state, acceptance, comments and results across turns and
+  instances.
+- Can't: substitute for chat consensus — a blocked card still needs the person
+  (or the dispatcher) to answer.
+- Code: the `task` tool (`src/channel/mcp-tools.ts:79-80`).
+- Refs: —
+
+## decision
+
+A recorded agreement (`post_decision`, `list_decisions`), scoped to a project
+directory or to the whole fleet. Decisions are the fleet's memory of why,
+readable with `list_decisions`.
+
+- Can: record agreements agents and people consult later.
+- Can't: enforce itself — code that never reads a decision is not bound by it
+  (see Mismatches).
+- Code: `post_decision`, `list_decisions` tool definitions.
+- Refs: —
+
+## credential profile
+
+A named credential set for one backend (`CREDENTIAL_HOMES`), so one fleet can
+act under several accounts. `/login <backend> <profile>` signs a profile in;
+chat sign-in from the fleet exists for some backends only.
+
+- Can: separate accounts per instance or backend.
+- Can't: share across backends — a profile belongs to its backend's home.
+- Code: `src/backend/credential-profile.ts:5-13`, `:266-295`.
+- Refs: —
+
+## native Windows agent / paired PC / runtime
+
+Today AgEnD runs on Linux and macOS (on Windows: under WSL, with desktop
+shortcuts from `agend shortcuts`). The rest is alpha only
+(`origin/release/2.3.5-alpha`, adapting the external #2934 — decision
+72353fdf).
+
+- A native Windows agent uses this PC's Windows-side CLI: AgEnD in WSL
+  discovers native Windows CLIs and runs Windows agents in the same fleet
+  registry as Linux agents (`runtimes.windows_cli`, off by default).
+- A paired PC is another Windows computer connected over HTTPS: it runs the
+  small `agend-runtime` runner (a ZIP from Settings, never a fleet), connects
+  outbound with a one-time pairing code, and joins only after its pairing
+  fingerprint is approved in Settings (#2936). Agents pinned to it keep their
+  working directories on that PC.
+- General can run on a Windows pane: "Run General on" moves General to an
+  approved, online paired PC while the coordinator — and chat and
+  administrator authority — stay on the host (#3007).
+- Pairing of people (`agend access pair`) is the separate, older mechanism:
+  per-instance access codes, unrelated to paired PCs.
+- Code (alpha branch): `docs/remote-runtime.md`, `docs/windows-cli-preview.md`,
+  `docs/windows-general.md`; `src/runtime-bundle.ts`.
+- Refs: 72353fdf, #2936, #3007.
+
+## public link (quick vs named)
+
+Temporary dashboard access for someone off the host. Quick: an auto-made
+`trycloudflare.com` tunnel URL with a short TTL. Named: the operator's own
+hostname, with a longer TTL. Guests may ride an open public link, but never
+with authority.
+
+- Can: show the dashboard (and, if switched on, search, the usage report,
+  Office shares) without a chat account.
+- Can't: admin surfaces that require the dashboard reached directly (guests,
+  web authority, the dashboard's own web settings).
+- Code: `src/config-validator.ts:424-429`;
+  `src/office-share-service.ts:6` (quick-tunnel 429s);
+  `src/public-preview.ts:4-5`.
+- Refs: `docs/named-tunnel.md`.
+
+## connections from outside (alpha only)
+
+`origin/release/2.3.5-alpha`: a web-only fleet may open itself to the
+internet — "Allow connections from outside" — and sign the outside browser in
+with an authenticator-app TOTP code (#3008; fleet decision 0471da59).
+
+- Can (alpha): reach the dashboard from outside without a tunnel the operator
+  builds; sign in with the authenticator app's code.
+- Can't: use it on main today — alpha only.
+- Code (alpha branch): `src/auth-api.ts` (`/auth/totp`);
+  `src/authority/web-authority.ts`.
+- Refs: #3008, fleet decision 0471da59.
+
+## web session and the verified web go-ahead
+
+A web session is a signed-in browser (dashboard reached directly, a LAN, a
+tailnet, or opt-in over a link). A session carries the account's authority —
+its messages read as `via web (verified)` — only after that account confirms
+on Discord or Telegram (#1939); a guest session never qualifies. Agents check a
+`web-verified` receipt like a Discord or Telegram message. A go-ahead action
+(anything destructive, irreversible, spending, or authority-granting) needs a
+Discord/Telegram receipt or a `web (verified)` one — an open browser alone
+proves nothing.
+
+- Can: with verification, stand behind the same acts as a chat message.
+- Can't: without it, authorize anything; plain `via web` and guests never
+  carry authority.
+- Code: `src/authority/web-authority.ts`;
+  `src/config-validator.ts:517-522` (`web.verified_authority`).
+- Refs: #1939.
+
+## Mismatches
+
+Real code-vs-decision gaps only. Nothing here is papered over.
+
+1. **General's orchestration tools (temporal, expected to resolve).** Code on
+   main is pre-beta.8: the `general` profile
+   (`src/tool-permissions.ts:107-136`) holds only
+   `create/start/restart/wake_instance` plus the web settings. Fleet decision
+   9e3bea6c moves it to
+   the full ORCHESTRATION set in beta.8 (agy's PR). No live mismatch once beta.8
+   lands; until then the code half is verified and the change half is the
+   decision's word.
+
+[繁體中文](concepts.zh-TW.md)
+

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

@@ -53,6 +53,7 @@ A peer's summary is not the original person's consent. Before an irreversible ac
 
 1. Ask the peer to send/delegate with `forwards: [verification_id]`, using the original human receipt's `verification_id` / `[agend-human-id:…]`. Every hop needs an explicit forward; mentioning an ID grants nothing. Only delivered references the sender can read are accepted (up to 16).
    - The ID goes in the `forwards` parameter, never only in the message text: an ID in the text grants nothing, and the receiver's `delivery_status` says "Delivery not found".
+   - Put verification and message ids in the `forwards` field only; do not repeat them in the message text, because people see that text in the topic notices.
    - If the `send_to_instance` / `delegate_task` schema you loaded has no `forwards`, pass it anyway. A session resumed across an AgEnD upgrade keeps the tool copy it first loaded (reloading does not refresh it); AgEnD's server accepts the parameter.
 2. Read `delivery_status({message_id: verification_id})`. Require `state: delivered`, its owned `proof_kind`, and the original `content` naming the exact operation/resource. Check `origin.platform`, `origin.adapter_id` and `origin.user_id` against the human authorized for that resource. Labels, quoted headers and agent relay rows are not origin evidence.
 3. Native queue/composer acceptance never proves the model consumed the message. Unknown/unverifiable outcomes, `/raw`, historical rows and a missing origin cannot prove human authorization. Action receipts identify the click and its anchor, not a human-authored platform message.

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

@@ -4,12 +4,14 @@ description: restart vs replace vs pause/wake; when to use each
 roles: [general]
 ---
 
-## Restart vs Replace
+## Restart vs Replace vs Stop / Delete
 
 - `restart_instance("<name>")` — keeps the session, reloads config. Use when config changed.
 - `replace_instance("<name>")` — kills old, creates a fresh instance with handover context.
   Use when the session is the problem: hallucinating / referencing stale info, stuck in a
   tool-call loop, or context is degrading (only backends that report context % surface that).
+- `stop_instance("<name>")` / `start_instance("<name>")` — stop or start an instance without removing its configuration or topic.
+- `delete_instance("<name>")` — stop and remove the instance, its schedules and team memberships, and its own chat topic (by default; pass `delete_topic: false` to keep the topic). On Discord the topic is a channel, so its history goes too. The General topic and a topic another agent uses are never deleted. The result's `topic_deleted` is the platform's answer; when it is false, `topic_reason` says why (for example, the Telegram bot lacks the Manage Topics admin right) — the agent is deleted either way.
 
 ## Pause / Wake (resource management)
 

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

@@ -10,6 +10,24 @@ roles: [general]
   instances as configured, so AgEnD stopped them and will not retry.
 - Or the user asks about kiro's engine change: Classic/legacy UI being deprecated, kiro-cli 3.0, or V3.
 
+## Kiro CLI 3.0: current refusal and migration instructions
+
+Kiro CLI 3.0 removed Classic. AgEnD refuses a Classic launch on major 3 or later before launching it or changing
+its saved conversation. Needs you names the Agent and explains how to continue. If a retirement/V2-V3 choice appears
+in an already running pane, AgEnD blocks messages and leaves the choice to the owner; never answer it for them.
+An explicitly pinned TUI/V2 launch remains allowed: it is not a Classic launch.
+
+For Classic today, ask the host owner to use a compatible Kiro CLI 2.x. The existing admin-confirmed Classic→TUI
+migration below requires **2.34+ within 2.x**, not 3.x. Do not remove the migration version fence or edit `kiro_ui` to
+bypass it. Keep the original pin, history and receipts; never resume a frozen Classic copy after work continued on V2.
+
+The guided **admin-confirmed migration on 2.x followed by a safe upgrade to 3.0 (plan C, #3047)** is coming separately.
+It is not implemented by this refusal/Needs-you change. Do not promise an automatic conversion or an upgrade date.
+
+繁體中文：Kiro CLI 3.0 已移除 Classic。請由主機管理者改用相容的 2.x；這個拒絕啟動的保護不會更動已存對話。
+既有管理員確認的 Classic→TUI 遷移只接受 2.34 以上的 **2.x**。先在 2.x 經管理員確認遷移、再安全升級到 3.0
+的引導流程（計畫 C，#3047）會另外提供，並未包含在這次保護裡。不要直接改 `kiro_ui` 或刪除版本檢查來繞過。
+
 ## What is true
 
 - **Each kiro instance's conversation lives in its engine's own store:**
@@ -56,11 +74,30 @@ The user has already been shown the plain notice in this topic. When they ask, e
 - 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.
 
+## Preparing for Kiro CLI 3.x
+
+1. Call `kiro_engine_status` with no name filter. Its `kiro3_readiness` summary counts **all** Kiro Agents and
+   Classic rooms, including General; filtering to one Agent still keeps that whole-fleet count. A Classic Agent
+   is not ready for Kiro 3.x. This readiness describes the removal of Classic, not a promise that every 3.x
+   release supports every session or tool.
+2. Keep a compatible Kiro **2.x** installed. For each Classic fleet Agent, ask the owner to confirm the existing
+   `migrate_kiro_instance` move described below. Do not change `kiro_ui` by hand. Wait for the same conversation
+   and model to pass both verification starts; failure stops the Agent for inspection. The migration itself is
+   unchanged and is not available on 3.x.
+3. A **ClassicBot room** cannot use `migrate_kiro_instance`: its owner must change the room to another backend
+   in Classic settings, or continue using Kiro 2.x. Such rooms count as still Classic until their effective Kiro
+   configuration no longer selects Classic. Do not present a fleet-Agent migration tool as room recovery.
+4. Check `kiro_engine_status` again: every remaining Kiro Agent must use TUI (or already use V3), and the
+   `still_classic` count must be zero before recommending an upgrade. General is subject to the same check.
+5. The owner then upgrades Kiro themselves. AgEnD neither installs the CLI nor answers a V2/V3 menu. If a menu
+   or an unverified resume blocks startup, inspect Needs-you; do not clear the pin or start a fresh conversation
+   to make the check pass. The version-specific exact-resume evidence is documented separately from readiness.
+
 ## Moving an instance from classic to the TUI engine (#2598)
 
 kiro-cli 3.0 drops the classic engine (`kiro_ui: legacy`), so classic instances are being moved to the TUI engine,
-**one batch at a time and only with the user's OK for that batch**. The move is `migrate_kiro_instance` (a
-coordinator-level tool; you do not have it). It carries the conversation: the instance's classic conversation is
+**one batch at a time and only with the user's OK for that batch**. The move is `migrate_kiro_instance` (available
+in the `general`, `coordinator` and `full` tool sets). It carries the conversation: the instance's classic conversation is
 resumed once under the TUI and becomes its own. A fleet admin confirms each move in this General topic: a
 "Move it / Cancel" prompt. Explain it if asked; never press it on the user's behalf.
 
@@ -92,8 +129,8 @@ session identity after `/chat` or `/clear`.
   this instance's. When it can't be proven, or the check passes its 30 s / 2 GiB limit, the instance resumes the
   conversation on record and the Log tab says why.
 - **Two conversations after an interrupted carry (#2753).** When a stopped TUI instance has its original carried
-  conversation and a newer one with work, recovery holds instead of choosing. `reconcile_kiro_instance` (full and
-  coordinator tool sets) asks a fleet admin to confirm, in General, keeping the original and archiving the named
+  conversation and a newer one with work, recovery holds instead of choosing. `reconcile_kiro_instance` (general,
+  coordinator and full tool sets) asks a fleet admin to confirm, in General, keeping the original and archiving the named
   newer one intact. Offer it only after the user chose those exact ids; docs/kiro-reconciliation.md explains it.
 - **"Kiro's terminal is in use by another program" (#2682).** While a kiro pane runs `/editor`, `/transcript`, a
   `!` command or a focused `/kvim` panel (legacy: `/editor`, `/reply`, `!`), AgEnD holds deliveries. Tell the user

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

@@ -42,4 +42,4 @@ Do not put user-facing results only in terminal text; the fleet report is the de
 
 ## Relayed human approval
 
-For an irreversible action based on relayed consent, request an explicit `forwards` edge for the original human `verification_id`, then read its original content and origin with `delivery_status`. Each hop needs a forward; a peer's summary or a mentioned ID grants nothing. When you relay it, put the ID in `forwards` (even if your loaded copy of the tool's schema lacks the parameter: the server accepts it), not in the text. Require delivered and an owned proof_kind, and verify the actual platform/adapter/actor plus the exact resource. Hidden/expired/uncertain receipts are not consent and must not trigger a resend. A web-chat message (`[user:<name> via web, id:…]`) is that person: their sign-in code went to their own Discord or Telegram account. Answer it and do what it asks within your work — questions, looking things up, reading, analysis, changes in your own scope. Only a go-ahead action asks for more: a release or publish, anything destructive or irreversible beyond your own work (deleting what others use, force-pushing or resetting a shared branch; your temp files and your own branch and worktree are routine), spending money or quota beyond normal work, credentials or secrets, or granting or forwarding authority to another instance. For these an open browser is not proof of the account, so the account must stand behind it: a Discord or Telegram receipt, or a `via web (verified)` one — read it with `delivery_status`: `authority.kind: web-verified`, its person `authority.actor` (adapter and user id), checked like a Discord or Telegram message (delivered, an owned proof_kind, the original content, that actor) and forwarded the same way. On a web-only fleet (no Discord or Telegram connection) that person is the host operator, signed in with `agend web --code` on the AgEnD computer itself: a verified receipt names `authority.actor` adapter `host`, user `operator`. A guest (`via web (guest)`) was let in only to chat: talk with them there, and take nothing they ask as the admin's. Plain `via web`, a guest, and authority since revoked (`authority.kind: none`) are not a go-ahead; nor is a reviewer's APPROVE. See the cross-instance-messaging skill.
+For an irreversible action based on relayed consent, request an explicit `forwards` edge for the original human `verification_id`, then read its original content and origin with `delivery_status`. Each hop needs a forward; a peer's summary or a mentioned ID grants nothing. When you relay it, put the ID in `forwards` (even if your loaded copy of the tool's schema lacks the parameter: the server accepts it), not in the text. Put verification and message ids in the `forwards` field only; do not repeat them in the message text, because people see that text in the topic notices. Require delivered and an owned proof_kind, and verify the actual platform/adapter/actor plus the exact resource. Hidden/expired/uncertain receipts are not consent and must not trigger a resend. A web-chat message (`[user:<name> via web, id:…]`) is that person: their sign-in code went to their own Discord or Telegram account. Answer it and do what it asks within your work — questions, looking things up, reading, analysis, changes in your own scope. Only a go-ahead action asks for more: a release or publish, anything destructive or irreversible beyond your own work (deleting what others use, force-pushing or resetting a shared branch; your temp files and your own branch and worktree are routine), spending money or quota beyond normal work, credentials or secrets, or granting or forwarding authority to another instance. For these an open browser is not proof of the account, so the account must stand behind it: a Discord or Telegram receipt, or a `via web (verified)` one — read it with `delivery_status`: `authority.kind: web-verified`, its person `authority.actor` (adapter and user id), checked like a Discord or Telegram message (delivered, an owned proof_kind, the original content, that actor) and forwarded the same way. On a web-only fleet (no Discord or Telegram connection) that person is the host operator, signed in with `agend web --code` on the AgEnD computer itself: a verified receipt names `authority.actor` adapter `host`, user `operator`. A guest (`via web (guest)`) was let in only to chat: talk with them there, and take nothing they ask as the admin's. Plain `via web`, a guest, and authority since revoked (`authority.kind: none`) are not a go-ahead; nor is a reviewer's APPROVE. See the cross-instance-messaging skill.

package/dist/instance-lifecycle.d.ts

@@ -1,5 +1,6 @@
 import { SettingsExecution } from "./settings-transaction.js";
 import type { InstanceConfig, FleetConfig } from "./types.js";
+import type { TopicDeleteOutcome } from "./instance-topic-delete.js";
 import { RoutingEngine } from "./routing-engine.js";
 import type { Logger } from "./logger.js";
 import type { IpcClient } from "./channel/ipc-bridge.js";
@@ -57,6 +58,7 @@ export declare function getUnsafeInstanceDaemonPidReason(pid: number, dataDir: s
  * FleetManager implements this.
  */
 export interface LifecycleContext {
+    readonly agentCredentials?: Pick<import("./agent-credentials.js").AgentCredentials, "issue" | "invalidate">;
     readonly fleetConfig: FleetConfig | null;
     readonly logger: Logger;
     readonly dataDir: string;
@@ -93,8 +95,10 @@ export interface LifecycleContext {
     createForumTopic(topicName: string, adapterId?: string): Promise<number | string>;
     /** #2910: no Discord or Telegram connection at all — a new agent gets no topic (it is reached from the dashboard). */
     isWebOnlyFleet?(): boolean;
-    /** adapterId selects the world, mirroring createForumTopic (rollback must delete where it created). */
-    deleteForumTopic(topicId: number | string, adapterId?: string): Promise<void>;
+    /** delete_instance: the removal, then (unless `deleteTopic` is false) the agent's own topic, through its own bot. */
+    removeInstanceAndTopic(name: string, authorization: ExplicitInstanceRemoval, opts: {
+        deleteTopic: boolean;
+    }): Promise<TopicDeleteOutcome>;
     /**
      * A bound delete for the world `adapterId` selects, captured by the caller
      * BEFORE awaiting createForumTopic. Rollback must use exactly this — never
@@ -135,6 +139,8 @@ export interface LifecycleContext {
     /** Notify a clean CLI exit and offer an admin-only restart action in General. */
     notifyNormalExit(name: string): Promise<void>;
     notifySessionOomStop?(name: string, unclear?: boolean): Promise<void>;
+    /** A pre-launch refusal is still a visible wait when no daemon was published. */
+    setKiroCompatibilityHold?(name: string, message: string | null): void;
     /** Tell every General, as an agent, that kiro-cli can no longer run this instance as configured. */
     queueKiroIncompatNotice?(name: string, reason: string): void;
     /** True for a dynamic ClassicBot channel instance (not a fleet topic). */

package/dist/instance-lifecycle.js

@@ -681,6 +681,24 @@ export class InstanceLifecycle {
             }
             this.ctx.notifyInstanceTopic(name, t("delivery.cancelled_unsent", messages.length, name));
         }, this.ctx.logger, `daemon.human_messages_cancelled[${name}]`));
+        // #3030: messages handed to the busy CLI's own queue that it never took (it went idle without them), or that a
+        // restart left unverifiable (its transcript could not be read, so they were not sent again). Each is marked ❌ and
+        // the person is told once — never a silent ✅.
+        daemon.on("human_handoffs_unsettled", safeHandler((data) => {
+            const messages = Array.isArray(data?.messages) ? data.messages : [];
+            if (!messages.length)
+                return;
+            const reason = data.reason === "unverifiable" ? "unverifiable" : "not-taken";
+            this.ctx.eventLog?.insert(name, "handoffs_unsettled", { reason, count: messages.length });
+            this.ctx.logger.warn({ name, reason, count: messages.length }, "Queued messages not taken by the CLI — telling the person");
+            for (const m of messages) {
+                if (this.ctx.finishDeliveryStatus)
+                    this.ctx.finishDeliveryStatus(name, m.chatId, m.messageId, "failed", m.threadId);
+                else
+                    this.ctx.reactMessageStatus(name, m.chatId, m.messageId, "failed", m.threadId);
+            }
+            this.ctx.notifyInstanceTopic(name, t(reason === "unverifiable" ? "delivery.handoff_unverified_after_restart" : "delivery.handoff_not_taken", messages.length, name));
+        }, this.ctx.logger, `daemon.human_handoffs_unsettled[${name}]`));
     }
     attachIncidentHandlers(name, daemon) {
         daemon.on("capacity_nudge_cancelled", safeHandler((data) => {
@@ -1367,6 +1385,7 @@ export class InstanceLifecycle {
     }
     /** Invalidate every start/wake already running for `name` (they will not publish). */
     invalidate(name) {
+        this.ctx.agentCredentials?.invalidate(name);
         this.lifecycleEpochs.set(name, this.epochOf(name) + 1);
     }
     /** Whether `transition` is `name`'s transition and is the one running now. */
@@ -1487,6 +1506,18 @@ export class InstanceLifecycle {
             backend: backendName,
             model: config.model ?? "default",
         }, this.ctx.spawnGate, this.ctx.stormWindow, this.ctx.backendOutage);
+        // Register before start: a pre-launch refusal has no published daemon or later incident handlers.
+        daemon.on("kiro_compatibility_hold", (message) => {
+            const owner = this.daemons.get(name);
+            if (owner ? owner !== daemon : this.epochOf(name) !== epoch)
+                return;
+            this.ctx.setKiroCompatibilityHold?.(name, message);
+        });
+        daemon.setAgentCredentialIssuer?.(token => {
+            if (this.epochOf(name) !== epoch)
+                throw new SupersededStartError(name);
+            this.ctx.agentCredentials?.issue(name, token);
+        });
         daemon.setDeliveryOutboxPort(this.ctx.deliveryOutbox ?? undefined);
         daemon.setWorkLeaseCheck(() => this.hasWorkLease(name));
         if (seedNow)
@@ -1580,6 +1611,7 @@ export class InstanceLifecycle {
             this.ctx.setTopicIcon(name, "green");
             this.ctx.touchActivity(name);
         });
+        this.ctx.setKiroCompatibilityHold?.(name, null);
         this.attachIncidentHandlers(name, daemon);
         // #2897: a new daemon starts with no dialog held; a notice the last one left (a crash, a respawn) is out of date.
         this.ctx.resolveParkedNotice?.(name);
@@ -2341,7 +2373,8 @@ export class InstanceLifecycle {
     /** Handle delete_instance tool call from a daemon. */
     async handleDelete(args, respond) {
         const instanceName = args.name;
-        const deleteTopic = args.delete_topic ?? false;
+        // The user's decision (beta.9): deleting an agent deletes its topic, unless `delete_topic: false` keeps it.
+        const deleteTopic = args.delete_topic ?? true;
         const instanceConfig = this.ctx.fleetConfig?.instances[instanceName];
         if (!instanceConfig) {
             respond(null, `Instance not found: ${instanceName}`);
@@ -2351,11 +2384,9 @@ export class InstanceLifecycle {
             respond(null, "Cannot delete the General instance");
             return;
         }
-        if (deleteTopic && instanceConfig.topic_id) {
-            await this.ctx.deleteForumTopic(instanceConfig.topic_id);
-        }
-        await this.ctx.removeInstance(instanceName, authorizeExplicitInstanceRemoval("delete-instance-tool"));
-        respond({ success: true, name: instanceName, topic_deleted: deleteTopic });
+        // topic_deleted is the platform's answer, never the request; when the topic stays, topic_reason says why.
+        const topic = await this.ctx.removeInstanceAndTopic(instanceName, authorizeExplicitInstanceRemoval("delete-instance-tool"), { deleteTopic });
+        respond({ success: true, name: instanceName, topic_deleted: topic.deleted, ...(topic.deleted ? {} : { topic_reason: topic.reason }) });
     }
     has(name) {
         return this.daemons.has(name);