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

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

@@ -0,0 +1,22 @@
+---
+name: cross-instance-messaging
+description: Fire-and-queue cross-instance tools — send once, never resend on queued
+---
+
+## How to send
+
+Use fleet tools only (`send_to_instance`, `delegate_task`, `request_information`, `report_result`, `broadcast`):
+- Call returns immediately: `{ sent: true, queued: true }` — success, fleet owns delivery.
+- **Do not wait** for the target to go idle; **do not** treat 30s IPC timeout as failure to re-send.
+- **Error only if the target does not exist** (or similar hard reject) — then fix the name, don't spam.
+- **Never re-send because the reply said `queued`** — that means the message is already queued.
+
+## requires_reply
+
+- Means “target should later answer with `report_result` / a real reply”
+- **Not** a synchronous wait for their turn to finish
+
+## Task flow
+
+- `delegate_task` → silent work → `report_result` (zero ack-only pings)
+- Cross-instance traffic is `[from:name]` → answer with `send_to_instance` / `report_result`, never `reply`

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

@@ -1,36 +1,27 @@
 ---
 name: model-discovery
-description: List available models per backend, configure model in fleet.yaml
+description: Set and discover models — pass-through to the CLI, no AgEnD allowlist gate
 ---
 
-## Model Names by Backend
+## How to set a model
 
-Models are specified in fleet.yaml `defaults.model` or per-instance `model` field.
+- 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)
 
-| Backend | How to list models | Default |
-|---------|-------------------|---------|
-| **kiro-cli** | In tmux: send `/model` + Enter → read model list → Esc to close | auto (latest) |
-| **claude-code** | `sonnet`, `opus`, `haiku`, `opusplan`, `best`, `sonnet[1m]`, `opus[1m]` | sonnet |
-| **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 |
-| **grok** | `grok-4.5`, `grok-4.3`, `grok-code`, `grok-build-0.1` | grok default |
+## Discover real names
 
-**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.
-- When setting model in fleet.yaml, use only the base name WITHOUT the effort suffix.
-- Example: `agy models` shows `Gemini 3.5 Flash (Medium)` → set `model: "Gemini 3.5 Flash"`
-- Example: `agy models` shows `Claude Opus 4.6 (Thinking)` → set `model: "Claude Opus 4.6"`
+| 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*`) |
+| grok | `grok models` |
+| antigravity | `agy models` — set **base name only** (drop `(Medium)` / `(Thinking)` effort suffix) |
+| opencode | `opencode models` |
 
-**Important:** Model names vary by backend. Always check the actual CLI output rather than guessing names.
-
-Example fleet.yaml:
 ```yaml
 defaults:
   backend: kiro-cli
   model: claude-sonnet-4-20250514
-
-instances:
-  heavy-task:
-    model: claude-opus-4-20250514
 ```

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

@@ -1,46 +1,27 @@
 ---
 name: session-management
-description: Where kiro-cli and claude-code store sessions, and how to fork one to a new instance
+description: Session stores, forking, and auth-pause recovery
 ---
 
+## Auth failure (auto-pause)
+
+When AgEnD sees `auth_error` it **pauses** that instance (`pausePending` sticky):
+- One notification **per backend** (not per instance) — log in once, same-backend peers recover.
+- Auth is **per-user global** across backends: claude-code, codex, kiro, grok, opencode, antigravity.
+- Messages while paused stay in the **queue** — do not re-send.
+- After the user re-auths: `wake` / normal wake clears `pausePending`.
+
 ## Where sessions live
 
 | | 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) |
-
-`<path-encoded>` = the absolute working_directory with `/` → `-`
-(e.g. `/home/han/Projects/AgEnD` → `-home-han-Projects-AgEnD`).
-
-## Fork a session to a new instance
-
-Confirm the source is **idle** first (`describe_instance` / `get_fleet_status`) — don't fork mid-task.
-
-**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"`.
-
-**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-encoded>/<session>.jsonl ~/.claude/projects/$TARGET_ENC/
-   ```
-4. Start the target — claude-code resumes the newest `.jsonl` via `--continue`.
+| Reload | `/chat load <file>` | `--continue` / `--resume <id>` |
 
-**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.
+`<path-encoded>` = absolute cwd with `/` → `-`.
 
-## Backup
+## Fork (source must be idle)
 
-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.
+- **kiro:** `/chat save name.json -f` → `create_instance` → copy workspace file → `/chat load name.json`
+- **claude-code:** copy newest `*.jsonl` into target's encoded project dir → start (uses `--continue`)
+- Prefer `replace_instance` when the whole session is poisoned (see instance-lifecycle)

package/dist/hang-detector.d.ts

@@ -1,16 +1,22 @@
 import { EventEmitter } from "node:events";
+/**
+ * Carries "this instance looks hung" from the daemon to the fleet manager.
+ *
+ * It is only an event bridge. Hang detection itself lives in the daemon's pane-state
+ * machine, which emits `hang` directly when a pane stops changing for the configured
+ * stuck timeout; `instance-lifecycle` subscribes to that and notifies.
+ *
+ * It used to also contain a silence-timer state machine — `start()`, `isHung()`,
+ * `hungEmitted`, and timestamps fed by `recordActivity` / `recordInbound` /
+ * `recordStatuslineUpdate`. None of it ran: `start()` was never called from
+ * anywhere, so `isHung()` was unreachable, the timestamps were written and never
+ * read, and the constructor's `timeoutMinutes` was ignored (the real stuck timeout
+ * is read separately by the pane monitor). Its tests exercised that dead logic —
+ * two had identical setup with contradictory expectations, which can only pass
+ * unnoticed when neither runs against anything real.
+ *
+ * Kept as a named class rather than a bare EventEmitter so the daemon → lifecycle
+ * wiring stays typed and greppable.
+ */
 export declare class HangDetector extends EventEmitter {
-    private lastActivityTs;
-    private lastStatuslineTs;
-    private lastInboundTs;
-    private hungEmitted;
-    private checkTimer;
-    private timeoutMs;
-    constructor(timeoutMinutes: number);
-    recordActivity(): void;
-    recordInbound(): void;
-    recordStatuslineUpdate(): void;
-    isHung(): boolean;
-    start(intervalMs?: number): void;
-    stop(): void;
 }

package/dist/hang-detector.js

@@ -1,53 +1,23 @@
 import { EventEmitter } from "node:events";
+/**
+ * Carries "this instance looks hung" from the daemon to the fleet manager.
+ *
+ * It is only an event bridge. Hang detection itself lives in the daemon's pane-state
+ * machine, which emits `hang` directly when a pane stops changing for the configured
+ * stuck timeout; `instance-lifecycle` subscribes to that and notifies.
+ *
+ * It used to also contain a silence-timer state machine — `start()`, `isHung()`,
+ * `hungEmitted`, and timestamps fed by `recordActivity` / `recordInbound` /
+ * `recordStatuslineUpdate`. None of it ran: `start()` was never called from
+ * anywhere, so `isHung()` was unreachable, the timestamps were written and never
+ * read, and the constructor's `timeoutMinutes` was ignored (the real stuck timeout
+ * is read separately by the pane monitor). Its tests exercised that dead logic —
+ * two had identical setup with contradictory expectations, which can only pass
+ * unnoticed when neither runs against anything real.
+ *
+ * Kept as a named class rather than a bare EventEmitter so the daemon → lifecycle
+ * wiring stays typed and greppable.
+ */
 export class HangDetector extends EventEmitter {
-    lastActivityTs = 0;
-    lastStatuslineTs = 0;
-    lastInboundTs = 0;
-    hungEmitted = false;
-    checkTimer = null;
-    timeoutMs;
-    constructor(timeoutMinutes) {
-        super();
-        this.timeoutMs = timeoutMinutes * 60 * 1000;
-    }
-    recordActivity() {
-        this.lastActivityTs = Date.now();
-        if (this.hungEmitted) {
-            this.hungEmitted = false;
-        }
-    }
-    recordInbound() {
-        this.lastInboundTs = Date.now();
-    }
-    recordStatuslineUpdate() {
-        this.lastStatuslineTs = Date.now();
-    }
-    isHung() {
-        if (this.lastActivityTs === 0)
-            return false;
-        if (this.lastInboundTs === 0)
-            return false;
-        const now = Date.now();
-        // Only flag as hung if:
-        // 1. There's an inbound that hasn't been answered (no activity since inbound)
-        // 2. Timeout has elapsed since that inbound
-        const noActivitySinceInbound = this.lastActivityTs < this.lastInboundTs;
-        const stale = now - this.lastInboundTs > this.timeoutMs;
-        return stale && noActivitySinceInbound;
-    }
-    start(intervalMs = 60_000) {
-        this.checkTimer = setInterval(() => {
-            if (this.isHung() && !this.hungEmitted) {
-                this.hungEmitted = true;
-                this.emit("hang");
-            }
-        }, intervalMs);
-    }
-    stop() {
-        if (this.checkTimer) {
-            clearInterval(this.checkTimer);
-            this.checkTimer = null;
-        }
-    }
 }
 //# sourceMappingURL=hang-detector.js.map

package/dist/hang-detector.js.map

@@ -1 +1 @@
-{"version":3,"file":"hang-detector.js","sourceRoot":"","sources":["../src/hang-detector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,OAAO,YAAa,SAAQ,YAAY;IACpC,cAAc,GAAG,CAAC,CAAC;IACnB,gBAAgB,GAAG,CAAC,CAAC;IACrB,aAAa,GAAG,CAAC,CAAC;IAClB,WAAW,GAAG,KAAK,CAAC;IACpB,UAAU,GAA0C,IAAI,CAAC;IACzD,SAAS,CAAS;IAE1B,YAAY,cAAsB;QAChC,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,SAAS,GAAG,cAAc,GAAG,EAAE,GAAG,IAAI,CAAC;IAC9C,CAAC;IAED,cAAc;QACZ,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACjC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,aAAa;QACX,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAClC,CAAC;IAED,sBAAsB;QACpB,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACrC,CAAC;IAED,MAAM;QACJ,IAAI,IAAI,CAAC,cAAc,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QAC5C,IAAI,IAAI,CAAC,aAAa,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,wBAAwB;QACxB,8EAA8E;QAC9E,4CAA4C;QAC5C,MAAM,sBAAsB,GAAG,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,aAAa,CAAC;QACxE,MAAM,KAAK,GAAG,GAAG,GAAG,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,SAAS,CAAC;QACxD,OAAO,KAAK,IAAI,sBAAsB,CAAC;IACzC,CAAC;IAED,KAAK,CAAC,UAAU,GAAG,MAAM;QACvB,IAAI,CAAC,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE;YACjC,IAAI,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;gBACvC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;gBACxB,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACpB,CAAC;QACH,CAAC,EAAE,UAAU,CAAC,CAAC;IACjB,CAAC;IAED,IAAI;QACF,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,aAAa,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC/B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACzB,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"hang-detector.js","sourceRoot":"","sources":["../src/hang-detector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,YAAa,SAAQ,YAAY;CAAG"}

package/dist/instance-lifecycle.d.ts

@@ -4,6 +4,7 @@ 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";
+import type { FleetInstructionsParams } from "./instructions.js";
 export interface BackendInstallationInfo {
     binary: string;
     install: string;
@@ -12,6 +13,14 @@ export interface BackendInstallationInfo {
 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;
+/** Whether a process command line identifies the shared AgEnD fleet process. */
+export declare function isFleetStartCommandLine(commandLine: string): boolean;
+/**
+ * Return why an instance daemon PID must not receive SIGTERM, or null when the
+ * stale-process cleanup may proceed. daemon.pid historically stores the shared
+ * in-process FleetManager PID, so this check is deliberately conservative.
+ */
+export declare function getUnsafeInstanceDaemonPidReason(pid: number, dataDir: string): string | null;
 /**
  * Context interface for instance lifecycle operations.
  * FleetManager implements this.
@@ -90,8 +99,19 @@ export declare class InstanceLifecycle {
     private ctx;
     /** Active daemon processes: instanceName → Daemon */
     readonly daemons: Map<string, import("./daemon.js").Daemon>;
+    /** backend → last auth-error alert time, so one expiry sends one alert. */
+    private lastAuthAlertAt;
     constructor(ctx: LifecycleContext);
-    start(name: string, config: InstanceConfig, topicMode: boolean): Promise<void>;
+    /** Backend a running instance uses (config → fleet default). */
+    private backendOf;
+    /**
+     * One alert per backend per cooldown, naming every affected instance — a CLI's
+     * credentials are shared, so N instances failing is ONE problem with ONE fix
+     * (re-login once). The per-instance daemon cooldown can't dedupe across
+     * instances, so the fleet-level map does it here.
+     */
+    private notifyAuthErrorOnce;
+    start(name: string, config: InstanceConfig, topicMode: boolean, runtimeIdentity?: FleetInstructionsParams["runtimeIdentity"]): Promise<void>;
     isPaused(name: string): boolean;
     getLastPausedAt(name: string): number | null;
     pause(name: string): Promise<void>;

package/dist/instance-lifecycle.js

@@ -29,14 +29,93 @@ export function checkBinaryInstalled(binary) {
         return false;
     }
 }
+/** Whether a process command line identifies the shared AgEnD fleet process. */
+export function isFleetStartCommandLine(commandLine) {
+    const normalized = commandLine.replace(/\0/g, " ").replace(/\s+/g, " ").trim();
+    return /\b(?:agend|(?:cli|daemon-entry)\.(?:js|ts))\b.*\bfleet\s+start\b/i.test(normalized);
+}
+function readProcessCommandLine(pid) {
+    try {
+        return readFileSync(`/proc/${pid}/cmdline`, "utf8").replace(/\0/g, " ").trim();
+    }
+    catch {
+        try {
+            return execFileSync("ps", ["-p", String(pid), "-o", "command="], {
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "ignore"],
+                timeout: 1000,
+            }).trim();
+        }
+        catch {
+            return "";
+        }
+    }
+}
+/**
+ * Return why an instance daemon PID must not receive SIGTERM, or null when the
+ * stale-process cleanup may proceed. daemon.pid historically stores the shared
+ * in-process FleetManager PID, so this check is deliberately conservative.
+ */
+export function getUnsafeInstanceDaemonPidReason(pid, dataDir) {
+    if (!Number.isSafeInteger(pid) || pid <= 1)
+        return "invalid or privileged PID";
+    if (pid === process.pid)
+        return "PID is the current shared fleet process";
+    try {
+        const fleetPid = Number.parseInt(readFileSync(join(dataDir, "fleet.pid"), "utf8").trim(), 10);
+        if (Number.isSafeInteger(fleetPid) && pid === fleetPid) {
+            return "PID matches fleet.pid";
+        }
+    }
+    catch {
+        // Missing/unreadable fleet.pid: fall through to the process command check.
+    }
+    const commandLine = readProcessCommandLine(pid);
+    if (commandLine && isFleetStartCommandLine(commandLine)) {
+        return "process command line is agend fleet start";
+    }
+    return null;
+}
+/** Suppress duplicate auth alerts for the same backend within this window. */
+const AUTH_ALERT_COOLDOWN_MS = 5 * 60_000;
 export class InstanceLifecycle {
     ctx;
     /** Active daemon processes: instanceName → Daemon */
     daemons = new Map();
+    /** backend → last auth-error alert time, so one expiry sends one alert. */
+    lastAuthAlertAt = new Map();
     constructor(ctx) {
         this.ctx = ctx;
     }
-    async start(name, config, topicMode) {
+    /** Backend a running instance uses (config → fleet default). */
+    backendOf(name) {
+        return this.ctx.fleetConfig?.instances[name]?.backend
+            ?? this.ctx.fleetConfig?.defaults?.backend
+            ?? "claude-code";
+    }
+    /**
+     * One alert per backend per cooldown, naming every affected instance — a CLI's
+     * credentials are shared, so N instances failing is ONE problem with ONE fix
+     * (re-login once). The per-instance daemon cooldown can't dedupe across
+     * instances, so the fleet-level map does it here.
+     */
+    notifyAuthErrorOnce(name, message) {
+        const backend = this.backendOf(name);
+        const now = Date.now();
+        const last = this.lastAuthAlertAt.get(backend) ?? 0;
+        if (now - last < AUTH_ALERT_COOLDOWN_MS) {
+            this.ctx.logger.info({ name, backend }, "auth error suppressed (backend already alerted)");
+            return;
+        }
+        this.lastAuthAlertAt.set(backend, now);
+        const affected = [...this.daemons.keys()].filter(n => this.backendOf(n) === backend);
+        const others = affected.filter(n => n !== name);
+        const scope = others.length
+            ? `${affected.length} instances on \`${backend}\`: ${affected.join(", ")}`
+            : `\`${name}\` (${backend})`;
+        this.ctx.notifyInstanceTopic(name, `🔑 ${message}\n\nAffects ${scope}. Credentials are shared per backend — one re-login restores all of them; affected instances pause until then.`);
+    }
+    async start(name, config, topicMode, runtimeIdentity) {
         if (this.daemons.has(name)) {
             this.ctx.logger.info({ name }, "Instance already running, skipping");
             return;
@@ -69,7 +148,11 @@ export class InstanceLifecycle {
             return;
         }
         const backend = createBackend(backendName, instanceDir);
-        const daemon = new Daemon(name, config, instanceDir, topicMode, backend, this.ctx.controlClient ?? undefined, this.ctx.logger);
+        const daemon = new Daemon(name, config, instanceDir, topicMode, backend, this.ctx.controlClient ?? undefined, this.ctx.logger, runtimeIdentity ?? {
+            kind: "fleet-topic",
+            backend: backendName,
+            model: config.model ?? "default",
+        });
         // 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");
@@ -127,17 +210,51 @@ export class InstanceLifecycle {
             this.ctx.eventLog?.insert(name, "snapshot_failed", {});
             this.ctx.notifyInstanceTopic(name, t("inst.restarted_no_context", name));
         }, this.ctx.logger, `daemon.snapshot_failed[${name}]`));
+        daemon.on("supervision_ended", safeHandler((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 });
+            this.ctx.logger.error({ name, reason: data.reason }, "Instance is no longer supervised");
+            this.ctx.notifyInstanceTopic(name, `🛑 ${name} is no longer running and will not be restarted automatically — ${data.reason}.\n${data.remedy}`);
+            this.ctx.setTopicIcon(name, "red");
+        }, this.ctx.logger, `daemon.supervision_ended[${name}]`));
+        daemon.on("health_check_error", safeHandler((data) => {
+            this.ctx.eventLog?.insert(name, "health_check_error", { message: data.message });
+            this.ctx.logger.error({ name, message: data.message }, "Health check failing — instance supervision degraded");
+            this.ctx.notifyInstanceTopic(name, `⚠️ ${name}: health check is failing (\`${data.message}\`). Crash detection for this instance may be degraded — see daemon.log.`);
+        }, this.ctx.logger, `daemon.health_check_error[${name}]`));
         daemon.on("crash_loop", safeHandler(() => {
             this.ctx.eventLog?.insert(name, "crash_loop", {});
             this.ctx.logger.error({ name }, "Instance in crash loop — respawn paused");
             this.ctx.notifyInstanceTopic(name, t("inst.respawn_paused", name));
             this.ctx.setTopicIcon(name, "red");
         }, this.ctx.logger, `daemon.crash_loop[${name}]`));
+        daemon.on("mcp_died", safeHandler((data) => {
+            this.ctx.eventLog?.insert(name, "mcp_died", { pid: data.pid });
+            this.ctx.logger.error({ name, pid: data.pid }, "MCP server died — instance cannot use agend tools");
+            this.ctx.webhookEmit("mcp_died", name, { pid: data.pid });
+            // The CLI owns the MCP server's stdio pipes, so only restarting the CLI can
+            // restore its tools — say so instead of implying self-healing. Deliberately
+            // NOT auto-restarting: that would interrupt whatever the agent is doing, and
+            // an instance whose CLI is otherwise fine may still be doing useful work.
+            this.ctx.notifyInstanceTopic(name, `⚠️ \`${name}\` 的 MCP server 已終止 — 這個 instance 目前無法使用 agend 工具（無法 reply / 跨 instance 通訊）。\n`
+                + `CLI 本身還在執行。工具只能由 CLI 自己重新啟動 MCP server，請用 \`restart_instance("${name}")\` 或 \`/restart\` 恢復。`);
+        }, this.ctx.logger, `daemon.mcp_died[${name}]`));
         daemon.on("pty_error", safeHandler((data) => {
             this.ctx.eventLog?.insert(name, "pty_error", { type: data.type, action: data.action });
             this.ctx.logger.warn({ name, errorType: data.type, action: data.action }, `PTY error: ${data.message}`);
             const emoji = data.type === "rate_limit" || data.type === "timeout" ? "⏳" : data.type === "auth_error" ? "🔑" : "⚠️";
-            this.ctx.notifyInstanceTopic(name, t("inst.notification", emoji, name, data.message, data.action));
+            // Auth failures are a property of the BACKEND's shared credentials, not of
+            // one instance: every instance on that CLI fails at once, and one re-login
+            // fixes them all. Notify once per backend (listing who's affected) instead
+            // of N near-identical alerts, and suppress repeats fleet-wide.
+            if (data.type === "auth_error") {
+                this.notifyAuthErrorOnce(name, data.message);
+            }
+            else {
+                this.ctx.notifyInstanceTopic(name, t("inst.notification", emoji, name, data.message, data.action));
+            }
             this.ctx.webhookEmit("pty_error", name, { type: data.type, action: data.action, message: data.message });
             // The CLI interrupted itself on this error, so any pending Cancel button is
             // now useless — retire it. We only reach here when the error wasn't
@@ -154,6 +271,17 @@ export class InstanceLifecycle {
                 // default (valid) model.
                 this.ctx.restartSingleInstance(name, { freshStart: true }).catch(err => this.ctx.logger.error({ err, name }, "pty_error restart failed"));
             }
+            else if (data.action === "pause") {
+                // Previously unhandled, so an expired session kept receiving messages and
+                // re-sending its whole context into a CLI that could only fail — wasted
+                // credit and lost work. pause() alone no-ops while the pane is busy (the
+                // usual state when auth fails), so mark it to pause as soon as it idles.
+                // Queued messages survive: delivery wakes a paused instance.
+                void this.pause(name)
+                    .catch(err => this.ctx.logger.warn({ err, name }, "auth-error pause failed"))
+                    .finally(() => { if (!this.isPaused(name))
+                    daemon.requestPauseWhenIdle(); });
+            }
         }, this.ctx.logger, `daemon.pty_error[${name}]`));
         daemon.on("pty_recovered", safeHandler((data) => {
             const mins = Math.floor(data.downtime_s / 60);
@@ -239,11 +367,17 @@ export class InstanceLifecycle {
             const pidPath = join(instanceDir, "daemon.pid");
             if (existsSync(pidPath)) {
                 const pid = parseInt(readFileSync(pidPath, "utf-8").trim(), 10);
-                try {
-                    process.kill(pid, "SIGTERM");
+                const unsafeReason = getUnsafeInstanceDaemonPidReason(pid, this.ctx.dataDir);
+                if (unsafeReason) {
+                    this.ctx.logger.error({ instance: name, pid, reason: unsafeReason, pidPath }, `Refusing to SIGTERM pid ${pid} — it is the shared fleet process, not a per-instance daemon`);
                 }
-                catch (e) {
-                    this.ctx.logger.debug({ err: e, pid }, "SIGTERM failed for stale process");
+                else {
+                    try {
+                        process.kill(pid, "SIGTERM");
+                    }
+                    catch (e) {
+                        this.ctx.logger.debug({ err: e, pid }, "SIGTERM failed for stale process");
+                    }
                 }
             }
             // Kill orphaned tmux window (daemon not in memory but window may persist)