@songsid/agend 2.1.4-beta.2 → 2.1.4-beta.21

package/dist/fleet-yaml-slim.d.ts

@@ -0,0 +1,10 @@
+import type { RawFleetConfig } from "./types.js";
+/**
+ * Instance identity/routing fields remain explicit even when they currently
+ * equal a fleet default. Removing one of these makes the YAML harder to audit
+ * and can change which external resource an instance represents.
+ */
+export declare const PRESERVED_INSTANCE_FIELDS: Set<string>;
+export type FleetConfigPath = Array<string | number>;
+/** Return raw YAML leaf paths that are redundant with effective defaults. */
+export declare function collectRedundantInstanceDefaultPaths(raw: RawFleetConfig): FleetConfigPath[];

package/dist/fleet-yaml-slim.js

@@ -0,0 +1,59 @@
+import { isDeepStrictEqual } from "node:util";
+import { getEffectiveInstanceDefaults } from "./config.js";
+/**
+ * Instance identity/routing fields remain explicit even when they currently
+ * equal a fleet default. Removing one of these makes the YAML harder to audit
+ * and can change which external resource an instance represents.
+ */
+export const PRESERVED_INSTANCE_FIELDS = new Set([
+    "working_directory",
+    "topic_id",
+    "channel_id",
+    "general_topic",
+    "description",
+    "tags",
+    "model",
+    "backend",
+    "backend_options",
+    "display_name",
+    "systemPrompt",
+    "worktree_source",
+    "profile",
+]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function collectMatchingLeaves(value, inherited, path, output) {
+    if (isRecord(value) && isRecord(inherited)) {
+        for (const [key, child] of Object.entries(value)) {
+            if (Object.prototype.hasOwnProperty.call(inherited, key)) {
+                collectMatchingLeaves(child, inherited[key], [...path, key], output);
+            }
+        }
+        return;
+    }
+    // Arrays are leaf values here: a partial array cannot inherit safely.
+    if (isDeepStrictEqual(value, inherited))
+        output.push(path);
+}
+/** Return raw YAML leaf paths that are redundant with effective defaults. */
+export function collectRedundantInstanceDefaultPaths(raw) {
+    const instances = raw.instances;
+    if (!instances || !isRecord(instances))
+        return [];
+    const effectiveDefaults = getEffectiveInstanceDefaults((raw.defaults ?? {}));
+    const redundant = [];
+    for (const [name, instance] of Object.entries(instances)) {
+        if (!isRecord(instance))
+            continue;
+        for (const [key, value] of Object.entries(instance)) {
+            if (PRESERVED_INSTANCE_FIELDS.has(key))
+                continue;
+            if (!Object.prototype.hasOwnProperty.call(effectiveDefaults, key))
+                continue;
+            collectMatchingLeaves(value, effectiveDefaults[key], ["instances", name, key], redundant);
+        }
+    }
+    return redundant;
+}
+//# sourceMappingURL=fleet-yaml-slim.js.map

package/dist/fleet-yaml-slim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fleet-yaml-slim.js","sourceRoot":"","sources":["../src/fleet-yaml-slim.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAC;AAG3D;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,IAAI,GAAG,CAAC;IAC/C,mBAAmB;IACnB,UAAU;IACV,YAAY;IACZ,eAAe;IACf,aAAa;IACb,MAAM;IACN,OAAO;IACP,SAAS;IACT,iBAAiB;IACjB,cAAc;IACd,cAAc;IACd,iBAAiB;IACjB,SAAS;CACV,CAAC,CAAC;AAIH,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,qBAAqB,CAC5B,KAAc,EACd,SAAkB,EAClB,IAAqB,EACrB,MAAyB;IAEzB,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QAC3C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACjD,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,EAAE,CAAC;gBACzD,qBAAqB,CAAC,KAAK,EAAE,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;YACvE,CAAC;QACH,CAAC;QACD,OAAO;IACT,CAAC;IAED,sEAAsE;IACtE,IAAI,iBAAiB,CAAC,KAAK,EAAE,SAAS,CAAC;QAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC7D,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,oCAAoC,CAClD,GAAmB;IAEnB,MAAM,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC;IAChC,IAAI,CAAC,SAAS,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO,EAAE,CAAC;IAElD,MAAM,iBAAiB,GAAG,4BAA4B,CACpD,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAA4B,CACrB,CAAC;IAC7B,MAAM,SAAS,GAAsB,EAAE,CAAC;IAExC,KAAK,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACzD,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;YAAE,SAAS;QAClC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;YACpD,IAAI,yBAAyB,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,SAAS;YACjD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,iBAAiB,EAAE,GAAG,CAAC;gBAAE,SAAS;YAC5E,qBAAqB,CACnB,KAAK,EACL,iBAAiB,CAAC,GAAG,CAAC,EACtB,CAAC,WAAW,EAAE,IAAI,EAAE,GAAG,CAAC,EACxB,SAAS,CACV,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC"}

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

@@ -0,0 +1,114 @@
+---
+name: backend-providers
+description: Configure custom model providers when creating or editing AgEnD Codex or OpenCode instances. Use for local, OpenAI-compatible, GLM, or other non-default provider endpoints and for backend_options provider selection.
+roles: [general]
+---
+
+# Backend Providers
+
+AgEnD selects a provider; the backend CLI owns endpoint and credential definitions.
+
+## Choose the backend
+
+| Backend | Provider configuration |
+|---|---|
+| 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. |
+
+## Create a Codex custom-provider instance
+
+1. Define the provider in the fleet user's `~/.codex/config.toml`. The table name is the provider ID used by AgEnD:
+
+```toml
+[model_providers.glm]
+name = "GLM"
+base_url = "https://provider.example.com/v1"
+env_key = "GLM_API_KEY"
+```
+
+Keep credentials out of `config.toml`. `env_key` names an environment variable; it is not the secret itself.
+
+2. Put the credential in the fleet process environment before startup. `~/.agend/.env` is the usual location:
+
+```dotenv
+GLM_API_KEY=replace-with-the-real-secret
+```
+
+Restart the fleet after changing its environment. Exporting a variable in an unrelated shell after the fleet has started does not update the running fleet process.
+
+3. Create the instance with the MCP tool:
+
+```json
+{
+  "directory": "/home/user/projects/my-project",
+  "topic_name": "glm-worker",
+  "backend": "codex",
+  "model": "GLM-5.2",
+  "backend_options": {
+    "codex": {
+      "provider": "glm"
+    }
+  }
+}
+```
+
+The equivalent per-instance fleet.yaml override is:
+
+```yaml
+instances:
+  glm-worker:
+    working_directory: /home/user/projects/my-project
+    backend: codex
+    model: GLM-5.2
+    backend_options:
+      codex:
+        provider: glm
+```
+
+AgEnD copies the user's Codex settings into the instance-isolated `CODEX_HOME`, then launches Codex with `model_provider="glm"`. Provider IDs may contain only letters, digits, `_`, and `-`.
+
+## Configure OpenCode
+
+Define the endpoint, SDK adapter, credentials, and models in OpenCode's `opencode.json` provider block:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "glm": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "GLM",
+      "options": {
+        "baseURL": "https://provider.example.com/v1",
+        "apiKey": "{env:GLM_API_KEY}"
+      },
+      "models": {
+        "GLM-5.2": {
+          "name": "GLM-5.2"
+        }
+      }
+    }
+  }
+}
+```
+
+Then use the fully qualified model ID in AgEnD:
+
+```yaml
+instances:
+  glm-opencode:
+    working_directory: /home/user/projects/my-project
+    backend: opencode
+    model: glm/GLM-5.2
+```
+
+OpenCode provider IDs and model IDs come from its own config. Do not use `backend_options.codex.provider` for OpenCode.
+
+## Verify and troubleshoot
+
+- Run `validate_config` before reload or restart.
+- Use `describe_instance` to verify the effective backend and model after creation.
+- If Codex says the provider is unknown, verify the `[model_providers.<id>]` table is in `~/.codex/config.toml` before the instance starts.
+- If authentication fails, verify the variable named by `env_key` exists in the fleet process environment; never paste the secret into fleet.yaml or `backend_options`.
+- A model-metadata fallback warning can be normal for a custom model with no built-in metadata. Provider connection, authentication, or unsupported-model errors are not normal and should still be investigated.

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

@@ -1,6 +1,7 @@
 ---
 name: cross-instance-messaging
 description: Fire-and-queue cross-instance tools — send once, never resend on queued
+roles: [general, worker]
 ---
 
 ## How to send
@@ -18,5 +19,6 @@ Use fleet tools only (`send_to_instance`, `delegate_task`, `request_information`
 
 ## Task flow
 
-- `delegate_task` → silent work → `report_result` (zero ack-only pings)
+- 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.
 - Cross-instance traffic is `[from:name]` → answer with `send_to_instance` / `report_result`, never `reply`

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

@@ -0,0 +1,52 @@
+---
+name: delegation-playbook
+description: Delegation protocol, loop prevention, parallel vs sequential execution, result/failure handling, team management, and instance configuration tips for the fleet coordinator
+roles: [general]
+---
+
+## Delegation Protocol
+
+Every delegation via send_to_instance() 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)
+
+### Loop Prevention
+
+- Never re-delegate a task back to the instance that sent it to you
+- If a task has bounced 3 times, stop and solve locally or reduce scope
+
+### Execution Strategy
+
+- Parallel — use only when tasks are independent with no shared state
+- Sequential — use when one task's output feeds into the next
+
+## Result Handling
+
+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.
+
+## 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.
+
+When instances disagree, collect both viewpoints, make a decision, and record it via post_decision.
+
+## Team Management
+
+- Always check existing teams before creating new ones
+- Default to ephemeral teams (created for a specific task, dissolved after completion)
+- Clean up ephemeral teams and instances after task completion
+
+## Instance Configuration Tips
+
+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.
+- **Cost control**: Set per-instance `cost_guard` for expensive backends.

package/dist/general-knowledge/skills/development-workflow/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: development-workflow
+description: The fleet-wide code-change policy the coordinator enforces when delegating code tasks — stages, review pairing, merge conditions
+roles: [general]
+---
+
+All code changes across the fleet should follow this workflow.
+The coordinator enforces compliance but does not perform these steps directly.
+Remind instances of this policy when delegating code tasks.
+
+## Workflow Stages
+
+Design Proposed → Design Approved → Implementation → Submit for Review → Under Review → Approved → Merge
+
+## Policy Rules
+
+1. Design before code — developer sends design proposal to reviewer before implementation. Consensus required before proceeding.
+2. Challenger pairing — every code task should have a developer + reviewer. Reviewer actively questions decisions and finds risks.
+3. Verify by execution — backend/CLI changes must be tested by running them. Do not trust documentation alone.
+4. Independent review — every merge requires code review from someone other than the author.
+5. Root cause first — bug fixes require confirmed root cause before proposing a fix.
+6. Merge conditions: tests pass, reviewer approved, branch and worktree cleaned up.
+
+## Specialist Instance Rules
+
+- Execute within defined scope only
+- Return structured output: result, assumptions, uncertainties, verification status
+- Do NOT create new instances without coordinator approval

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

@@ -1,6 +1,7 @@
 ---
 name: fleet-config
 description: fleet.yaml and classicBot.yaml structure, validation, common mistakes
+roles: [general]
 ---
 
 ## Configuration Quick Reference

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

@@ -1,6 +1,7 @@
 ---
 name: fleet-health
 description: Check instance health and what an agent is doing; recover a stuck instance
+roles: [general]
 ---
 
 ## Check health

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

@@ -1,6 +1,7 @@
 ---
 name: fleet-restart
 description: Fleet restart types, recovery from tmux crash, rate limit handling, safe update
+roles: [general]
 ---
 
 ## Fleet Restart & Recovery

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

@@ -1,6 +1,7 @@
 ---
 name: instance-lifecycle
 description: restart vs replace vs pause/wake; when to use each
+roles: [general]
 ---
 
 ## Restart vs Replace

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

@@ -1,27 +1,75 @@
 ---
 name: model-discovery
-description: Set and discover models — pass-through to the CLI, no AgEnD allowlist gate
+description: Choose and discover models — when to omit, per-backend defaults, pass-through
+roles: [general, worker]
 ---
 
-## How to set a model
+## Omit the model unless you have a reason
 
-- fleet.yaml: `defaults.model` or per-instance `model`
-- **Pass-through:** AgEnD no longer blocks unknown model ids — it may **warn**, then still pass the string to the CLI
-- **CLI is source of truth** — if the model is invalid, the backend CLI errors (fix the name there)
+Precedence: **explicit arg > `fleet.defaults.model` > CLI/account default**
+
+Omitting is the default answer. It inherits the fleet default, or the CLI's own —
+which is the account's current best model and stays right as the vendor ships new
+ones. A model you pin today is a model someone has to un-pin later.
+
+Pass a model only when: the user named one, the instance needs a *specific*
+capability (cheap/fast vs deep reasoning), or the backend needs one to behave
+(see kiro below).
+
+## Per-backend default behaviour
+
+| 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` |
+| codex | account default | |
+| grok | account default | |
+| antigravity | account default | |
+| opencode | provider default | ids are **`provider/model`**, e.g. `opencode/big-pickle` |
 
 ## Discover real names
 
-| Backend | How |
-|---------|-----|
-| kiro-cli | In pane: `/model` (gpt-*, deepseek-*, minimax-*, glm-*, qwen* supported) |
-| claude-code | `sonnet` / `opus` / `haiku` / `opusplan` / `Fable` / aliases |
-| codex | pane `/model` or docs (`gpt-*`, `o*`) |
+**Use the `list_models` tool** — it reads the fleet's probe cache (refreshed every
+24h) 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
+
+Check `scope` in the reply. An instance on a custom provider can offer a
+different catalog than the account (a Codex instance with `provider: glm` reads
+its own catalog), so `scope: "instance"` is authoritative for that instance and
+`scope: "global"` is only the account-wide list. `source` tells you `cache` /
+`live` / `fallback`.
+
+An empty list is **not** a failure — see pass-through below.
+
+Underlying commands, if you need them by hand:
+
+| Backend | Command |
+|---|---|
+| kiro-cli | `kiro-cli --list-models` |
 | grok | `grok models` |
-| antigravity | `agy models` — set **base name only** (drop `(Medium)` / `(Thinking)` effort suffix) |
 | opencode | `opencode models` |
+| antigravity | `agy models` |
+| codex | **no command** — the CLI writes `models_cache.json` in its CODEX_HOME |
+| claude-code | fixed alias set (no command) |
+
+## Setting one on create_instance
+
+- No specific need → **omit `model`**
+- Kiro, want per-turn selection → `model: "auto"`
+- Custom provider → pass the **full id** and set `backend_options`, e.g.
+  `backend: "codex"`, `backend_options: { codex: { provider: "glm" } }`
+- opencode → always `provider/model`, never a bare model name
+
+## 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)`).
 
-```yaml
-defaults:
-  backend: kiro-cli
-  model: claude-sonnet-4-20250514
-```
+**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
+valid, and a typo fails *in the CLI at launch*, not at config time — if an
+instance won't start after a model change, suspect the name first.

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

@@ -1,6 +1,7 @@
 ---
 name: multi-channel
 description: Setting up multiple platforms (Telegram + Discord) with proper general routing
+roles: [general]
 ---
 
 ## Multi-Channel Setup

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

@@ -1,6 +1,7 @@
 ---
 name: scheduling
 description: Cron, one-shot, and silent schedules via the schedule MCP tools
+roles: [general, worker]
 ---
 
 ## Tools

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

@@ -1,6 +1,7 @@
 ---
 name: session-management
 description: Session stores, forking, and auth-pause recovery
+roles: [general]
 ---
 
 ## Auth failure (auto-pause)

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

@@ -1,6 +1,7 @@
 ---
 name: tui-effort
 description: 在 Kiro CLI TUI instance 中，透過 tmux 查看或設定模型的 reasoning effort
+roles: [general]
 ---
 
 # Kiro TUI Effort

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

@@ -0,0 +1,30 @@
+---
+name: worker-collaboration
+description: Complete assigned fleet work as a worker, report the result to the assigning instance, and request missing information without taking over coordinator duties.
+roles: [worker]
+---
+
+# Worker Collaboration
+
+## Complete assigned work
+
+- 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.
+- Do not call `delegate_task`; delegation and fleet orchestration belong to General.
+
+## Request missing information
+
+Use `request_information` only when a concrete missing fact blocks safe progress. Ask the assigning instance one focused question and preserve the task correlation ID when the tool supports it.
+
+Do not resend after a timeout without checking delivery evidence. A timeout can mean the request was queued or delivered while the caller stopped waiting.
+
+## Report the result
+
+Call `report_result` exactly once when the assignment is complete or genuinely blocked. Send it to the assigning instance with the original correlation ID. Include:
+
+- the conclusion or delivered artifact;
+- material changes and file paths;
+- tests or checks run and their results;
+- remaining risk, blocker, or follow-up, if any.
+
+Do not put user-facing results only in terminal text; the fleet report is the delivery channel.

package/dist/instance-lifecycle.d.ts

@@ -51,6 +51,8 @@ export interface LifecycleContext {
     notifyInstanceTopic(name: string, text: string): void;
     /** Notify the blocked instance and offer an interactive assist action in General. */
     notifyInteractivePrompt(name: string, kind: string): Promise<void>;
+    /** Notify a clean CLI exit and offer an admin-only restart action in General. */
+    notifyNormalExit(name: string): Promise<void>;
     /** True for a dynamic ClassicBot channel instance (not a fleet topic). */
     isClassicInstance?(name: string): boolean;
     /** True while the fleet is stopping on purpose or an `agend update` is running. */
@@ -73,6 +75,10 @@ export interface LifecycleContext {
 export interface IncidentEventSource {
     on(event: string, handler: (...args: any[]) => void): unknown;
     requestPauseWhenIdle(): void;
+    /** Present on real daemons; hang buttons attach only when it returns one. */
+    getHangDetector?(): {
+        on(event: string, handler: (...args: any[]) => void): unknown;
+    } | null;
 }
 /** Arguments accepted by handleCreate — mirrors CreateInstanceArgs in outbound-schemas.ts
  *  plus internal-only fields forwarded by deploy_template (profile-derived). */
@@ -82,6 +88,8 @@ export interface LifecycleCreateArgs {
     description?: string;
     model?: string;
     backend?: string;
+    /** Backend-specific launch options, e.g. { codex: { provider: "glm" } }. */
+    backend_options?: Record<string, Record<string, unknown>>;
     branch?: string;
     detach?: boolean;
     worktree_path?: string;

package/dist/instance-lifecycle.js

@@ -165,6 +165,39 @@ export class InstanceLifecycle {
      * means a real tmux window, which is why this rule went untested before.
      */
     attachIncidentHandlers(name, daemon) {
+        const hangDetector = daemon.getHangDetector?.();
+        if (hangDetector) {
+            hangDetector.on("hang", safeHandler(async (data) => {
+                this.ctx.eventLog?.insert(name, "hang_detected", {});
+                this.ctx.logger.warn({ name }, "Instance appears hung");
+                if (this.ctx.isPlannedRestart()) {
+                    // A graceful stop makes every pane look frozen; alerting on that (with
+                    // a restart button, no less) during `agend update` is pure noise. The
+                    // same suppression interactive-prompt and normal-exit already apply.
+                    // Checked BEFORE the task nudge: injecting new work into a CLI that is
+                    // being shut down would only delay the stop.
+                    this.ctx.logger.info({ name }, "Hang notification suppressed — planned restart in progress");
+                    return;
+                }
+                // Check if instance has claimed tasks — nudge it to continue
+                const claimedTasks = this.ctx.listClaimedTasks(name);
+                if (claimedTasks.length > 0) {
+                    const task = claimedTasks[0];
+                    this.ctx.eventLog?.insert(name, "idle_task_nudge", { taskId: task.id, taskTitle: task.title });
+                    // Inject nudge message into the instance's CLI session
+                    const ipc = this.ctx.instanceIpcClients.get(name);
+                    if (ipc?.connected) {
+                        ipc.send({
+                            type: "fleet_inbound",
+                            content: `[system] You have a claimed task: "${task.title}" (#${task.id}). Continue working on it, or use task(done) / task(update, status=blocked) to update status.`,
+                            meta: { chat_id: "", thread_id: "", ts: new Date().toISOString() },
+                        });
+                    }
+                }
+                await this.ctx.sendHangNotification(name, data?.unchangedForMs);
+                this.ctx.webhookEmit("hang", name);
+            }, this.ctx.logger, `hangDetector[${name}]`));
+        }
         daemon.on("crash_respawn", safeHandler(() => {
             this.ctx.eventLog?.insert(name, "crash_respawn", {});
             this.ctx.logger.warn({ name }, "Instance crashed and respawned");
@@ -178,11 +211,22 @@ export class InstanceLifecycle {
             this.ctx.eventLog?.insert(name, "snapshot_failed", {});
             this.notifyIncident(name, "snapshot_failed", t("inst.restarted_no_context", name));
         }, this.ctx.logger, `daemon.snapshot_failed[${name}]`));
-        daemon.on("supervision_ended", safeHandler((data) => {
+        daemon.on("supervision_ended", safeHandler(async (data) => {
             // The instance is dead and nothing will restart it. Say so where the operator
             // is looking, and mark the topic — otherwise messages routed here just queue
             // or fail with a bare ❌ and the dashboard still looks normal.
             this.ctx.eventLog?.insert(name, "supervision_ended", { reason: data.reason });
+            if (data.exitCode === 0) {
+                this.ctx.logger.info({ name, exitCode: data.exitCode }, "CLI exited normally and will not restart automatically");
+                if (this.ctx.isPlannedRestart()) {
+                    this.ctx.logger.info({ name }, "Normal-exit controls suppressed — planned restart in progress");
+                }
+                else {
+                    await this.ctx.notifyNormalExit(name);
+                }
+                this.ctx.setTopicIcon(name, "red");
+                return;
+            }
             this.ctx.logger.error({ name, reason: data.reason }, "Instance is no longer supervised");
             this.notifyIncident(name, "supervision_ended", `🛑 ${name} is no longer running and will not be restarted automatically — ${data.reason}.\n${data.remedy}`);
             this.ctx.setTopicIcon(name, "red");
@@ -349,30 +393,6 @@ export class InstanceLifecycle {
         });
         await daemon.start();
         this.daemons.set(name, daemon);
-        const hangDetector = daemon.getHangDetector();
-        if (hangDetector) {
-            hangDetector.on("hang", safeHandler(async (data) => {
-                this.ctx.eventLog?.insert(name, "hang_detected", {});
-                this.ctx.logger.warn({ name }, "Instance appears hung");
-                // Check if instance has claimed tasks — nudge it to continue
-                const claimedTasks = this.ctx.listClaimedTasks(name);
-                if (claimedTasks.length > 0) {
-                    const task = claimedTasks[0];
-                    this.ctx.eventLog?.insert(name, "idle_task_nudge", { taskId: task.id, taskTitle: task.title });
-                    // Inject nudge message into the instance's CLI session
-                    const ipc = this.ctx.instanceIpcClients.get(name);
-                    if (ipc?.connected) {
-                        ipc.send({
-                            type: "fleet_inbound",
-                            content: `[system] You have a claimed task: "${task.title}" (#${task.id}). Continue working on it, or use task(done) / task(update, status=blocked) to update status.`,
-                            meta: { chat_id: "", thread_id: "", ts: new Date().toISOString() },
-                        });
-                    }
-                }
-                await this.ctx.sendHangNotification(name, data?.unchangedForMs);
-                this.ctx.webhookEmit("hang", name);
-            }, this.ctx.logger, `hangDetector[${name}]`));
-        }
         daemon.on("auto_pause_requested", safeHandler(async () => {
             await this.pause(name);
         }, this.ctx.logger, `autoPause[${name}]`));
@@ -782,6 +802,7 @@ export class InstanceLifecycle {
                 ...(systemPrompt ? { systemPrompt } : {}),
                 ...(args.model ? { model: args.model } : {}),
                 ...(args.backend ? { backend: args.backend } : {}),
+                ...(args.backend_options ? { backend_options: args.backend_options } : {}),
                 ...(args.model_failover ? { model_failover: args.model_failover } : {}),
                 ...(args.tool_set ? { tool_set: args.tool_set } : {}),
                 ...(args.skipPermissions != null ? { skipPermissions: args.skipPermissions } : {}),