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

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

@@ -5,6 +5,9 @@ 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";
+import { type ProviderUsage } from "./usage/providers.js";
+import type { SpawnGate } from "./spawn-gate.js";
+import type { StormWindow } from "./storm-window.js";
 export { isFleetStartCommandLine } from "./fleet-lock.js";
 export interface BackendInstallationInfo {
     binary: string;
@@ -34,6 +37,8 @@ export interface LifecycleContext {
     readonly sessionRegistry: Map<string, string>;
     readonly eventLog: EventLog | null;
     readonly controlClient: TmuxControlClient | null;
+    readonly spawnGate?: SpawnGate;
+    readonly stormWindow?: StormWindow;
     getInstanceDir(name: string): string;
     saveFleetConfig(): void;
     /** Full stop+start. freshStart forces the respawn to skip session resume. */
@@ -57,6 +62,8 @@ export interface LifecycleContext {
     isClassicInstance?(name: string): boolean;
     /** True while the fleet is stopping on purpose or an `agend update` is running. */
     isPlannedRestart(): boolean;
+    /** Suppress only incident kinds caused by the active tmux server storm. */
+    stormSuppressed?(kind: string): boolean;
     /** List claimed tasks for an instance (from task board). Returns empty array if unavailable. */
     listClaimedTasks(assignee: string): Array<{
         id: string;
@@ -66,6 +73,10 @@ export interface LifecycleContext {
     checkModelFailover(name: string, fiveHourPct: number): void;
     /** Retire (delete) any pending Cancel button for an instance. No-op if none. */
     clearCancelButton(name: string): void;
+    /** Test/integration seam for the non-LLM Codex quota second opinion. */
+    verifyCodexQuota?(): Promise<CodexQuotaVerdict>;
+    /** Test/integration seam for the non-LLM Claude quota second opinion. */
+    verifyClaudeQuota?(): Promise<ClaudeQuotaVerdict>;
     startStatuslineWatcher(name: string): void;
     stopStatuslineWatcher(name: string): void;
     reactMessageStatus(instanceName: string, chatId: string, messageId: string, emoji: string): void;
@@ -88,6 +99,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;
@@ -111,12 +124,45 @@ export interface LifecycleReplaceArgs {
     name: string;
     reason?: string;
 }
+export type CodexQuotaVerdict = "available" | "exhausted" | "unknown";
+type CodexUsageResult = Omit<ProviderUsage, "id" | "name">;
+export type ClaudeQuotaVerdict = "available" | "exhausted" | "unknown";
+type ClaudeUsageResult = Omit<ProviderUsage, "id" | "name">;
+/**
+ * Convert the live Codex usage row into a conservative quota verdict. A
+ * successful response with at least one window below 100% proves that stale
+ * terminal text is no longer current only when no other window is exhausted.
+ * Missing credentials, API errors, and metric-less responses prove nothing.
+ */
+export declare function codexQuotaVerdictFromUsage(usage: CodexUsageResult): CodexQuotaVerdict;
+/** Run only the Codex usage provider, bounded independently of its network timeout. */
+export declare function verifyCodexQuotaStatus(fetchUsage?: () => Promise<CodexUsageResult>, timeoutMs?: number): Promise<CodexQuotaVerdict>;
+/**
+ * Convert a LIVE Claude usage API row into a conservative verdict. The
+ * provider can degrade to statusline data when the network/API is unavailable;
+ * that fallback is intentionally unknown because stale local limits cannot
+ * disprove a current API credit-balance error.
+ */
+export declare function claudeQuotaVerdictFromUsage(usage: ClaudeUsageResult): ClaudeQuotaVerdict;
+/** Run only the Claude usage provider, bounded independently of its network timeout. */
+export declare function verifyClaudeQuotaStatus(fetchUsage?: () => Promise<ClaudeUsageResult>, timeoutMs?: number): Promise<ClaudeQuotaVerdict>;
 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;
+    /**
+     * backend → cached token-free auth verification (see AUTH_VERIFY_CACHE_MS).
+     * The PROMISE is cached, not the result: a shared credential expiring makes
+     * every instance of the backend fire in the same tick, and they must join
+     * one in-flight check instead of each spawning their own.
+     */
+    private authVerifyCache;
+    /** Same-tick Codex quota alerts join one live usage probe. */
+    private codexQuotaVerifyInFlight;
+    /** Same-tick Claude quota alerts join one live usage probe. */
+    private claudeQuotaVerifyInFlight;
     /**
      * Minimum gap between MCP-revival auto-restarts of one instance. Kept here —
      * not in the daemon — because each restart replaces the daemon object, which
@@ -143,6 +189,27 @@ export declare class InstanceLifecycle {
     private notifyIncident;
     /** Backend a running instance uses (config → fleet default). */
     private backendOf;
+    /**
+     * Confirm a pane-detected auth error with the backend's token-free status
+     * probe before pausing anything: pattern matching over terminal text also
+     * fires on an agent DISCUSSING a 401. "valid" means false positive — ignore.
+     * "invalid" and "unknown" (timeout, missing binary) both pause: for a
+     * suspected expiry, pausing too much is recoverable, delivering into a dead
+     * CLI is not. Cached per backend so simultaneous alerts run one check.
+     */
+    private verifyAuthError;
+    private verifyCodexQuota;
+    private verifyClaudeQuota;
+    /** Same verification keyed by backend (used by startup pre-flight priming). */
+    verifyBackendAuth(backend: string): Promise<"valid" | "invalid" | "unknown">;
+    /**
+     * Startup pre-flight: warm the per-backend auth verification cache so the
+     * detectors that fire seconds later (login-screen scan, MCP-died gate) get an
+     * instant answer. Advisory only — a pre-flight result alone never pauses
+     * anything, because e.g. codex on a custom provider runs fine while
+     * `codex login status` reports logged out (live-verified on this fleet).
+     */
+    primeAuthVerification(backends: Iterable<string>): void;
     /**
      * 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