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

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/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 (plus its schedules and team memberships; pass `delete_topic: true` to delete its topic as well).
 
 ## 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/instance-lifecycle.d.ts

@@ -135,6 +135,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) => {
@@ -1487,6 +1505,13 @@ 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.setDeliveryOutboxPort(this.ctx.deliveryOutbox ?? undefined);
         daemon.setWorkLeaseCheck(() => this.hasWorkLease(name));
         if (seedNow)
@@ -1580,6 +1605,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);