@songsid/agend 2.1.0-beta.4 → 2.1.0-beta.41

package/dist/fleet-system-prompt.js

@@ -43,7 +43,7 @@ User messages arrive as text in your prompt with a prefix:
 ### Scheduling
 | Tool | Purpose |
 |------|---------|
-| \`create_schedule\` | Create a cron-based scheduled task |
+| \`create_schedule\` | Create a recurring cron or one-shot scheduled task |
 | \`list_schedules\` | List all schedules |
 | \`update_schedule\` | Update a schedule |
 | \`delete_schedule\` | Delete a schedule |

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

@@ -30,29 +30,35 @@ templates:        # Reusable fleet deployment templates
 - Instance logs: `~/.agend/instances/<name>/output.log`
 - Fleet log: `~/.agend/fleet.log`
 
+## kiro-cli UI mode (kiro_ui)
+
+For `backend: kiro-cli` instances, `kiro_ui` selects the CLI's UI/agent profile:
+```yaml
+instances:
+  my-kiro:
+    backend: kiro-cli
+    kiro_ui: legacy    # default — current stable behavior
+    # kiro_ui: tui     # try the newer TUI
+    # kiro_ui: v3      # try the v3 profile
+```
+Leave unset (or `legacy`) unless testing a newer profile. Ignored by other backends.
+
 ## Config Validation
 
-**Before editing fleet.yaml or classicBot.yaml, always validate after:**
+**After editing fleet.yaml or classicBot.yaml, validate before reloading:**
+- `validate_config` MCP tool (preferred) — checks channels, instances, backends,
+  access, and both yaml files. Reports errors **and** warnings.
+- CLI equivalent: `agend validate`
 
-```bash
-# Validate fleet.yaml syntax
-agend fleet start --dry-run 2>&1 | head -5
-# Or simply:
-node -e "const yaml = require('js-yaml'); const fs = require('fs'); yaml.load(fs.readFileSync('$HOME/.agend/fleet.yaml', 'utf-8')); console.log('✓ valid YAML')"
-```
+Fix all errors before `agend reload`; warnings are advisory.
 
 **Common fleet.yaml mistakes:**
 - Missing `channel.mode` field → error on start
 - Wrong indentation (YAML is indent-sensitive)
 - `topic_id` as string vs number (both work, but be consistent)
-- `backend` typo (valid: `claude-code`, `gemini-cli`, `codex`, `opencode`, `kiro-cli`, `antigravity`)
+- `backend` typo (valid: `claude-code`, `gemini-cli`, `codex`, `opencode`, `kiro-cli`, `antigravity`, `grok`)
 - `model` using wrong format for the backend
 
-**classicBot.yaml validation:**
-```bash
-node -e "const yaml = require('js-yaml'); const fs = require('fs'); yaml.load(fs.readFileSync('$HOME/.agend/classicBot.yaml', 'utf-8')); console.log('✓ valid YAML')"
-```
-
 **Common classicBot.yaml mistakes:**
 - `allowed_guilds` values must be strings (Discord IDs are too large for YAML integers)
 - Channel IDs as keys must be quoted strings

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

@@ -1,55 +1,34 @@
 ---
 name: fleet-health
-description: Check instance health via tmux, detect stuck agents, fleet-wide health scan
+description: Check instance health and what an agent is doing; recover a stuck instance
 ---
 
-## Instance Health Check via tmux
-
-When user asks to check an instance's status or what it's doing:
-- Use `execute_bash` to run: `tmux capture-pane -t agend:<instance-name> -p | tail -20`
-- This shows the actual CLI screen (what the agent sees right now)
-- More useful than just "running/stopped" status
-- If the instance appears stuck, suggest `/raw /compact` or restart
-
-## Fleet Health Check
-
-Check all instances for stuck/error state:
-
-```bash
-for win in $(tmux list-windows -t agend -F '#{window_name}' | grep -v bash); do
-  last=$(tmux capture-pane -t "agend:$win" -p | tail -3 | tr '\n' ' ')
-  if echo "$last" | grep -q "!>"; then
-    echo "✅ $win — idle"
-  elif echo "$last" | grep -q "error:"; then
-    echo "❌ $win — ERROR"
-  else
-    echo "⏳ $win — busy"
-  fi
-done
-```
-
-States:
-- ✅ idle — prompt visible (X% !>), ready for input
-- ⏳ busy — processing a task, wait for it to finish
-- ❌ error — check tmux pane for details, may need restart
-
-If an instance is stuck (busy for >10 minutes with no output), restart it:
-- `restart_instance("<instance-name>")`
-
-## Unsticking a Frozen Instance via tmux
-
-If an instance is frozen (not responding, no output, no prompt):
-1. Send Ctrl+C via tmux to interrupt the current operation:
-   ```bash
-   tmux send-keys -t agend:<instance-name> C-c
-   ```
-2. Wait a few seconds, then check if it returned to idle:
-   ```bash
-   tmux capture-pane -t agend:<instance-name> -p | tail -5
-   ```
-3. If it shows the prompt (`X% !>` or `(To exit the CLI...)`) — it's unstuck. Resend the task.
-4. If still frozen after Ctrl+C, use `restart_instance("<instance-name>")`
-
-**When to use Ctrl+C vs restart:**
-- Ctrl+C: instance is alive but stuck on a long operation (API timeout, large file read, infinite loop)
-- restart: instance is completely dead (no tmux pane, crash loop, or Ctrl+C doesn't help)
+## Check health
+
+Prefer the fleet tools — they already know each instance's state:
+- `get_fleet_status` — status + execution state (idle / working / stuck) for every instance.
+- `describe_instance("<name>")` — one instance's status, last activity, description.
+- `list_instances` — quick roster.
+
+The daemon derives idle/working/stuck itself (per-backend), so you do **not** need to
+scrape prompts. Don't hand-write pane-text checks like `X% !>` — that prompt is
+kiro-specific and wrong for claude-code / codex / grok / antigravity.
+
+## See what an agent is actually doing
+
+When the user wants the live screen (not just a status word):
+- `get_instance_logs("<name>")` — recent output.
+- Raw terminal (last resort, no tool for the live pane):
+  `tmux capture-pane -t agend:<name> -p | tail -20`
+
+## Recover a stuck instance
+
+Do this when the user asks, or confirm first — don't silently restart others' work.
+- `restart_instance("<name>")` — reloads config, keeps the session. First choice for a
+  dead/looping instance.
+- `replace_instance("<name>")` — fresh instance with handover context, when the session
+  itself is the problem (see instance-lifecycle skill).
+
+A genuinely wedged CLI can sometimes be freed without a restart by interrupting it —
+that is the cancel key, exposed to users as the Cancel button / `/cancel`. Only drop to
+`tmux send-keys -t agend:<name> C-c` (kiro) / `Escape` (others) if the tools aren't enough.

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

@@ -26,7 +26,7 @@ description: Fleet restart types, recovery from tmux crash, rate limit handling,
 **Update AgEnD to latest version:**
 ```bash
 agend update              # update to latest
-agend update --version 0.0.6  # pin specific version
+agend update --version 2.1.0  # pin a specific version
 ```
 
 The `agend update` command automatically:

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

@@ -1,20 +1,26 @@
 ---
 name: instance-lifecycle
-description: Replace vs restart instances, monitoring state, when to use each
+description: restart vs replace vs pause/wake; when to use each
 ---
 
-## Instance Lifecycle Management
+## Restart vs Replace
 
-**Replace vs Restart:**
-- `restart_instance` — keeps session, reloads config. Use when config changed.
-- `replace_instance` — kills old, creates fresh with handover context. Use when context is polluted or instance is stuck in a loop.
+- `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).
 
-**When to replace (not restart):**
-- Instance keeps hallucinating or referencing stale information
-- Instance is stuck in a tool-call loop
-- Context is reported >80% full and responses are degrading (only applicable to backends that report context usage)
+## Pause / Wake (resource management)
 
-**Monitoring instance state:**
-- `describe_instance("<name>")` — shows status, last activity, description
-- `tmux capture-pane -t agend:<name> -p | tail -20` — see actual CLI screen
-- Look for `X% !>` prompt = idle, `Thinking...` = busy, `error` = needs attention
+- `pause_instance("<name>")` — stop the resident CLI but keep the instance; frees resources.
+- `wake_instance("<name>")` — bring a paused instance back.
+- Instances also pause automatically: `auto_pause_after` (idle minutes) and `warm_cap`
+  (fleet-wide cap — the least-recently-active idle instance is paused when over the cap).
+  The **general** instance is never auto-paused.
+- You don't need to wake before sending work: delivery wakes a paused instance first.
+
+## Monitoring state
+
+- `get_fleet_status` / `describe_instance("<name>")` — status + idle/working/stuck + last
+  activity (the daemon derives the state; don't scrape pane prompts).
+- For the raw screen, see the fleet-health skill (`get_instance_logs` / tmux capture).

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

@@ -14,11 +14,7 @@ Models are specified in fleet.yaml `defaults.model` or per-instance `model` fiel
 | **antigravity** | Run `agy models` to see available models | Gemini 3.5 Flash (Medium) |
 | **codex** | `gpt-4o`, `o3`, `o4-mini` | gpt-4o |
 | **opencode** | `opencode models` | depends on provider |
-
-**To discover available models for a backend, run the CLI's model listing command:**
-- `agy models` — lists all available models for antigravity
-- `opencode models` — lists all available models for opencode
-- `codex` — check config.toml
+| **grok** | `grok-4.5`, `grok-4.3`, `grok-code`, `grok-build-0.1` | grok default |
 
 **Important for antigravity (agy):**
 - `agy models` shows names like `Gemini 3.5 Flash (Medium)` — the parenthetical suffix (Medium/High/Low/Thinking) is the **effort level**, NOT part of the model name.

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

@@ -0,0 +1,41 @@
+---
+name: scheduling
+description: Cron, one-shot, and silent schedules via the schedule MCP tools
+---
+
+## Tools
+
+- `create_schedule` — make a schedule (recurring or one-shot).
+- `list_schedules` — list all (optionally filter by target instance).
+- `update_schedule` — change cron/at/message/timezone/enabled of an existing one.
+- `delete_schedule` — remove one.
+
+A schedule injects `message` into the `target` instance when it fires
+(`target` defaults to the current instance).
+
+## Three ways to schedule
+
+**1. Recurring (cron)** — `cron` + optional `timezone` (IANA, default `Asia/Taipei`):
+```
+create_schedule({ cron: "0 9 * * *", message: "Daily standup summary", timezone: "Asia/Taipei" })
+```
+Cron is 5-field (min hour dom mon dow). `0 9 * * *` = 09:00 daily in the given tz.
+
+**2. One-shot (at)** — `at` = ISO-8601 datetime **with offset**; runs once then auto-deletes:
+```
+create_schedule({ at: "2026-07-26T14:00:00+08:00", message: "Ship the release", target: "dev1" })
+```
+Exactly one of `cron` / `at` is required (mutually exclusive).
+
+**3. Silent** — add `silent: true` to any of the above. The message is pasted straight
+into the target's tmux pane instead of posting to the channel — use for heartbeats /
+background nudges the user shouldn't see:
+```
+create_schedule({ cron: "*/30 * * * *", message: "check CI and self-report if red", silent: true })
+```
+
+## Notes
+
+- `timezone` is per-schedule; the fire time is fixed to that zone (DST-safe).
+- Give recurring schedules a `label` so `list_schedules` / `delete_schedule` are easy.
+- One-shot (`at`) needs no cleanup — it deletes itself after firing.

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

@@ -1,133 +1,46 @@
 ---
 name: session-management
-description: Save/load/fork sessions, batch backup, reviewer session setup, kiro-cli and claude-code session paths
+description: Where kiro-cli and claude-code store sessions, and how to fork one to a new instance
 ---
 
-## kiro-cli Session Storage
+## Where sessions live
 
-kiro-cli automatically stores conversation sessions at:
-- **Path:** `~/.kiro/sessions/cli/<uuid>.json`
-- Each session is a JSON file with the full conversation history
-- Sessions persist across restarts — kiro-cli auto-resumes the latest session for each working directory
-
-**Useful for:**
-- Manual backup: `cp ~/.kiro/sessions/cli/*.json ~/backup/`
-- Finding a specific session: `ls -lt ~/.kiro/sessions/cli/ | head -5`
-- Loading a session into a new instance via `pre_task_command: "/chat load <path>"`
-
-## Reviewer Session Management
-
-For reviewer instances using kiro-cli:
-- Recommend setting `pre_task_command: "/chat load reviewer-base.json"` in fleet.yaml
-- This loads a base session with review guidelines on every restart
-- Help user create the base session:
-  1. Attach to reviewer: `agend attach <reviewer-instance>`
-  2. Set up review context and guidelines
-  3. Save: `/chat save reviewer-base.json -f`
-  4. Add to fleet.yaml under the reviewer instance config:
-     ```yaml
-     instances:
-       reviewer-xxx:
-         pre_task_command: "/chat load reviewer-base.json"
-     ```
-
-## Fork Instance (Session Cloning)
-
-When user wants to fork/clone an instance's session to a new instance:
-
-Steps:
-1. Wait for source instance to be idle (check with tmux capture-pane, look for "X% !>" prompt)
-
-2. Save current session on source instance via tmux:
-   - `execute_bash`: `tmux send-keys -t agend:<source-instance> '/chat save YYYYMMDD.json -f' Enter`
-   - Wait a few seconds for save to complete
-
-3. Create new instance:
-   - `create_instance` with same backend and working_directory (or new one)
-
-4. Copy session file to new instance workspace:
-   - `execute_bash`: `cp ~/.agend/workspaces/<source>/YYYYMMDD.json ~/.agend/workspaces/<target>/`
-
-5. Wait for new instance to be idle, then load session via tmux:
-   - `execute_bash`: `tmux send-keys -t agend:<new-instance-name> '/chat load YYYYMMDD.json' Enter`
-   - Or configure `pre_task_command: "/chat load YYYYMMDD.json"` for auto-load on restart
-
-## Claude Code Session Storage & Fork
-
-claude-code stores conversation sessions as JSONL, **keyed by the project (working) directory**:
-- **Path:** `~/.claude/projects/<project-path-encoded>/*.jsonl`
-- `<project-path-encoded>` is the absolute working_directory with `/` replaced by `-`
-  (e.g. `/home/han/Projects/AgEnD` → `-home-han-Projects-AgEnD`)
-- Each `.jsonl` is one session (full message history). Latest = most recently modified.
-
-**Key difference from kiro-cli:** claude-code has **no `/chat save` / `/chat load`**. You resume
-only via `--continue` (latest session for this dir) or `--resume <id>`. `/export` produces
-plain text only — it **cannot** be reloaded as a session. So forking is done by **copying the
-`.jsonl` file**, not by save/load commands.
+| | kiro-cli | claude-code |
+|---|---|---|
+| Store | `~/.kiro/sessions/cli/<uuid>.json` | `~/.claude/projects/<path-encoded>/*.jsonl` |
+| Keyed by | session uuid | project (working) directory |
+| Reload | `/chat load <file>` | none — `--continue` (latest for the dir) / `--resume <id>` |
+| Text export | — | `/export` (plain text, **not** reloadable) |
 
-### Fork a claude-code session to a new instance
+`<path-encoded>` = the absolute working_directory with `/` → `-`
+(e.g. `/home/han/Projects/AgEnD` → `-home-han-Projects-AgEnD`).
 
-1. **Confirm source instance is idle** — `tmux capture-pane -t agend:<source> -p | tail -5`
-   (look for the ready prompt, e.g. `❯`). Don't fork mid-task.
+## Fork a session to a new instance
 
-2. **Find the source session file** (newest first):
-   ```bash
-   ls -lt ~/.claude/projects/<source-path-encoded>/*.jsonl | head -5
-   ```
+Confirm the source is **idle** first (`describe_instance` / `get_fleet_status`) — don't fork mid-task.
 
-3. **Create the new instance** with `create_instance` (backend: `claude-code`). Note its
-   `working_directory` — it determines the target project path.
+**kiro-cli** — save, copy, load:
+1. On the source, save: `/chat save <name>.json -f` (paste via tmux if needed).
+2. `create_instance` (same backend).
+3. `cp ~/.agend/workspaces/<source>/<name>.json ~/.agend/workspaces/<target>/`
+4. Load on the target: `/chat load <name>.json`, or set `pre_task_command: "/chat load <name>.json"`.
 
-4. **Copy the `.jsonl` into the new instance's encoded project dir:**
+**claude-code** — copy the `.jsonl` (no save/load command):
+1. Newest source session: `ls -lt ~/.claude/projects/<source-encoded>/*.jsonl | head`
+2. `create_instance` (backend `claude-code`); note its working_directory.
+3. Copy into the target's encoded project dir:
    ```bash
    TARGET_ENC="$(echo '<target-working-dir>' | sed 's#/#-#g')"
    mkdir -p ~/.claude/projects/$TARGET_ENC
-   cp ~/.claude/projects/<source-path-encoded>/<session>.jsonl \
-      ~/.claude/projects/$TARGET_ENC/
+   cp ~/.claude/projects/<source-encoded>/<session>.jsonl ~/.claude/projects/$TARGET_ENC/
    ```
+4. Start the target — claude-code resumes the newest `.jsonl` via `--continue`.
 
-5. **Start/restart the new instance** — the claude-code backend resumes via `--continue`
-   (it auto-picks the latest session for that project dir), so the copied session is continued.
-
-### Caveats
-- **Same project path required:** a session can only resume under the working_directory it
-  was recorded in. If the target dir differs, claude-code still loads it via `--continue`
-  (it reads the newest `.jsonl` in the target's encoded dir), but file paths/context inside
-  the transcript will refer to the original dir.
-- `/export` = text only, not reloadable. Use the raw `.jsonl`.
-- Pick the **right** `.jsonl` if multiple exist (sort by mtime; each branch/compaction can
-  create new files).
-
-### kiro-cli vs claude-code fork (summary)
-| | kiro-cli | claude-code |
-|---|---|---|
-| Store | `~/.kiro/sessions/cli/<uuid>.json` | `~/.claude/projects/<path-encoded>/*.jsonl` |
-| Keyed by | session uuid | project (working) directory |
-| Fork method | `/chat save` → copy → `/chat load` | copy `.jsonl` → `--continue` |
-| Reload command | `/chat load <file>` | none — `--continue` / `--resume` only |
-| Text export | — | `/export` (not reloadable) |
-
-## Batch Session Backup
-
-Save all instances' sessions to a dated backup directory:
-
-```bash
-DATE=$(date +%Y%m%d)
-BACKUP_DIR="$HOME/.agend/session-backups/$DATE"
-mkdir -p "$BACKUP_DIR"
-MY_NAME="<your-own-instance-name>"  # skip yourself to avoid paste collision
-for win in $(tmux list-windows -t agend -F '#{window_name}' | grep -v bash); do
-  if [ "$win" = "$MY_NAME" ]; then continue; fi
-  tmux send-keys -t "agend:$win" "/chat save $BACKUP_DIR/${win}.json -f" Enter
-  sleep 3
-done
-```
+**Caveats:** a claude-code session only truly makes sense under its original working_directory
+(paths inside the transcript refer to it). Pick the right `.jsonl` if several exist (newest by
+mtime; compaction/branches create new files). `/export` is text only, not reloadable.
 
-Important:
-- Skip your own instance (the one executing this) to avoid paste collision
-- Use `sleep 3` between saves
-- Run fleet health check first — only backup idle instances
-- Do NOT backup while instances are busy
+## Backup
 
-Restore a single instance:
-- `tmux send-keys -t agend:<instance> '/chat load /path/to/backup.json' Enter`
+Sessions are plain files — back them up by copying the store paths above
+(e.g. `cp ~/.kiro/sessions/cli/*.json <dest>/`). Only copy while the instance is idle.

package/dist/instance-lifecycle.d.ts

@@ -4,6 +4,14 @@ import type { Logger } from "./logger.js";
 import type { IpcClient } from "./channel/ipc-bridge.js";
 import type { EventLog } from "./event-log.js";
 import type { TmuxControlClient } from "./tmux-control.js";
+export interface BackendInstallationInfo {
+    binary: string;
+    install: string;
+}
+/** Shared CLI metadata used by startup validation and ClassicBot onboarding. */
+export declare const BACKEND_INSTALLATION_INFO: Readonly<Record<string, BackendInstallationInfo>>;
+/** Check one executable using the same PATH visible to the fleet process. */
+export declare function checkBinaryInstalled(binary: string): boolean;
 /**
  * Context interface for instance lifecycle operations.
  * FleetManager implements this.
@@ -20,6 +28,10 @@ export interface LifecycleContext {
     readonly controlClient: TmuxControlClient | null;
     getInstanceDir(name: string): string;
     saveFleetConfig(): void;
+    /** Full stop+start. freshStart forces the respawn to skip session resume. */
+    restartSingleInstance(name: string, opts?: {
+        freshStart?: boolean;
+    }): Promise<void>;
     connectIpcToInstance(name: string): Promise<void>;
     createForumTopic(topicName: string, adapterId?: string): Promise<number | string>;
     deleteForumTopic(topicId: number | string): Promise<void>;
@@ -27,7 +39,7 @@ export interface LifecycleContext {
     /** Remove instance with full cleanup (scheduler, IPC, routing, config). */
     removeInstance(name: string): Promise<void>;
     touchActivity(name: string): void;
-    sendHangNotification(name: string): Promise<void>;
+    sendHangNotification(name: string, unchangedForMs?: number): Promise<void>;
     notifyInstanceTopic(name: string, text: string): void;
     /** List claimed tasks for an instance (from task board). Returns empty array if unavailable. */
     listClaimedTasks(assignee: string): Array<{
@@ -39,7 +51,9 @@ export interface LifecycleContext {
     /** Retire (delete) any pending Cancel button for an instance. No-op if none. */
     clearCancelButton(name: string): void;
     startStatuslineWatcher(name: string): void;
+    stopStatuslineWatcher(name: string): void;
     reactMessageStatus(instanceName: string, chatId: string, messageId: string, emoji: string): void;
+    startPersistedPausedInstance(name: string): Promise<void>;
 }
 /** Arguments accepted by handleCreate — mirrors CreateInstanceArgs in outbound-schemas.ts
  *  plus internal-only fields forwarded by deploy_template (profile-derived). */

package/dist/instance-lifecycle.js

@@ -8,6 +8,27 @@ import { sanitizeInstanceName } from "./topic-commands.js";
 import { isModelCompatible } from "./backend/types.js";
 import { safeHandler } from "./safe-async.js";
 import { t } from "./locale.js";
+import { clearPausedMarker, hasPausedMarker, readPausedAt, writePausedMarker } from "./pause-marker.js";
+/** Shared CLI metadata used by startup validation and ClassicBot onboarding. */
+export const BACKEND_INSTALLATION_INFO = {
+    "claude-code": { binary: "claude", install: "curl -fsSL https://claude.ai/install.sh | bash" },
+    "gemini-cli": { binary: "gemini", install: "npm i -g @google/gemini-cli" },
+    "kiro-cli": { binary: "kiro-cli", install: "brew install --cask kiro-cli" },
+    codex: { binary: "codex", install: "npm i -g @openai/codex" },
+    opencode: { binary: "opencode", install: "curl -fsSL https://opencode.ai/install | bash" },
+    antigravity: { binary: "agy", install: "curl -fsSL https://antigravity.google/cli/install.sh | bash" },
+    grok: { binary: "grok", install: "curl -fsSL https://x.ai/cli/install.sh | bash" },
+};
+/** Check one executable using the same PATH visible to the fleet process. */
+export function checkBinaryInstalled(binary) {
+    try {
+        execFileSync("which", [binary], { stdio: "pipe", timeout: 2000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 export class InstanceLifecycle {
     ctx;
     /** Active daemon processes: instanceName → Daemon */
@@ -35,18 +56,9 @@ export class InstanceLifecycle {
         const { createBackend } = await import("./backend/factory.js");
         const backendName = config.backend ?? this.ctx.fleetConfig?.defaults?.backend ?? "claude-code";
         // Verify backend binary is in PATH before spawning
-        const binaryMap = {
-            "claude-code": "claude", "codex": "codex", "gemini-cli": "gemini",
-            "opencode": "opencode", "kiro-cli": "kiro-cli", "antigravity": "agy",
-        };
-        const bin = binaryMap[backendName];
-        if (bin) {
-            try {
-                execFileSync("which", [bin], { stdio: "pipe", timeout: 2000 });
-            }
-            catch {
-                this.ctx.logger.error({ binary: bin, backend: backendName, instance: name }, `Backend binary "${bin}" not found in PATH`);
-            }
+        const installation = BACKEND_INSTALLATION_INFO[backendName];
+        if (installation && !checkBinaryInstalled(installation.binary)) {
+            this.ctx.logger.error({ binary: installation.binary, backend: backendName, instance: name }, `Backend binary "${installation.binary}" not found in PATH`);
         }
         // claude-code refuses --dangerously-skip-permissions as root — fail fast
         // Unless IS_SANDBOX=1 is set (recognized sandbox environment)
@@ -57,7 +69,7 @@ export class InstanceLifecycle {
             return;
         }
         const backend = createBackend(backendName, instanceDir);
-        const daemon = new Daemon(name, config, instanceDir, topicMode, backend, this.ctx.controlClient ?? undefined);
+        const daemon = new Daemon(name, config, instanceDir, topicMode, backend, this.ctx.controlClient ?? undefined, this.ctx.logger);
         // Catch errors from daemon internals (e.g. IPC server) to prevent crashing the fleet process
         daemon.on("error", (err) => {
             this.ctx.logger.error({ err, name }, "Daemon emitted error — instance isolated");
@@ -66,7 +78,7 @@ export class InstanceLifecycle {
         this.daemons.set(name, daemon);
         const hangDetector = daemon.getHangDetector();
         if (hangDetector) {
-            hangDetector.on("hang", safeHandler(async () => {
+            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
@@ -84,7 +96,7 @@ export class InstanceLifecycle {
                         });
                     }
                 }
-                await this.ctx.sendHangNotification(name);
+                await this.ctx.sendHangNotification(name, data?.unchangedForMs);
                 this.ctx.webhookEmit("hang", name);
             }, this.ctx.logger, `hangDetector[${name}]`));
         }
@@ -135,6 +147,13 @@ export class InstanceLifecycle {
             if (data.action === "failover") {
                 this.ctx.checkModelFailover(name, 100); // Force failover trigger
             }
+            else if (data.action === "restart") {
+                // A broken *resumed* session (e.g. agy pinned to a dead model) can't
+                // self-recover; a plain restart would --continue back into it. freshStart
+                // makes the respawn skip resume so the CLI starts a clean session on its
+                // default (valid) model.
+                this.ctx.restartSingleInstance(name, { freshStart: true }).catch(err => this.ctx.logger.error({ err, name }, "pty_error restart failed"));
+            }
         }, this.ctx.logger, `daemon.pty_error[${name}]`));
         daemon.on("pty_recovered", safeHandler((data) => {
             const mins = Math.floor(data.downtime_s / 60);
@@ -164,22 +183,49 @@ export class InstanceLifecycle {
         this.ctx.touchActivity(name);
     }
     isPaused(name) {
-        return this.daemons.get(name)?.isPaused ?? false;
+        return this.daemons.get(name)?.isPaused ?? hasPausedMarker(this.ctx.getInstanceDir(name));
     }
     getLastPausedAt(name) {
-        return this.daemons.get(name)?.lastPausedAt ?? null;
+        return this.daemons.get(name)?.lastPausedAt ?? readPausedAt(this.ctx.getInstanceDir(name));
     }
     async pause(name) {
         const daemon = this.daemons.get(name);
-        if (!daemon)
+        if (!daemon) {
+            if (hasPausedMarker(this.ctx.getInstanceDir(name)))
+                return;
             throw new Error(`Cannot pause stopped instance '${name}'`);
-        await daemon.pause();
+        }
+        this.ctx.stopStatuslineWatcher(name);
+        try {
+            await daemon.pause();
+        }
+        finally {
+            // A rejected/no-op pause leaves the instance active and must not strand
+            // its fleet-level statusline watcher in the frozen state.
+            if (!daemon.isPaused)
+                this.ctx.startStatuslineWatcher(name);
+        }
     }
     async wake(name, timeoutMs = 30_000) {
         const daemon = this.daemons.get(name);
-        if (!daemon)
-            throw new Error(`Cannot wake stopped instance '${name}'`);
-        await daemon.wake(timeoutMs);
+        if (daemon) {
+            await daemon.wake(timeoutMs);
+        }
+        else {
+            const instanceDir = this.ctx.getInstanceDir(name);
+            if (!hasPausedMarker(instanceDir))
+                throw new Error(`Cannot wake stopped instance '${name}'`);
+            const pausedAt = readPausedAt(instanceDir) ?? Date.now();
+            clearPausedMarker(instanceDir);
+            try {
+                await this.ctx.startPersistedPausedInstance(name);
+            }
+            catch (err) {
+                writePausedMarker(instanceDir, pausedAt);
+                throw err;
+            }
+        }
+        this.ctx.startStatuslineWatcher(name);
     }
     async stop(name) {
         this.ctx.setTopicIcon(name, "remove");
@@ -326,6 +372,7 @@ export class InstanceLifecycle {
         // Remove from fleet config and save
         delete this.ctx.fleetConfig.instances[name];
         this.ctx.saveFleetConfig();
+        clearPausedMarker(this.ctx.getInstanceDir(name));
         this.ctx.logger.info({ name }, "Instance removed");
     }
     /** Handle create_instance tool call from a daemon. */
@@ -474,6 +521,8 @@ export class InstanceLifecycle {
             const explicitTopicName = args.topic_name;
             const nameBase = explicitTopicName ?? (worktreePath ? topicName : (directory ? basename(workDir) : topicName));
             newInstanceName = `${sanitizeInstanceName(nameBase)}-t${createdTopicId}`;
+            // A recycled name must never inherit a stale pause marker.
+            clearPausedMarker(this.ctx.getInstanceDir(newInstanceName));
             // If no directory was provided, auto-create default workspace
             if (!directory) {
                 workDir = join(getAgendHome(), "workspaces", newInstanceName);