@songsid/agend 2.1.4-beta.5 → 2.1.4-beta.50

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
+description: Session stores, forking, cross-backend session recovery, and auth-pause recovery
+roles: [general]
 ---
 
 ## Auth failure (auto-pause)
@@ -11,17 +12,180 @@ When AgEnD sees `auth_error` it **pauses** that instance (`pausePending` sticky)
 - Messages while paused stay in the **queue** — do not re-send.
 - After the user re-auths: `wake` / normal wake clears `pausePending`.
 
-## Where sessions live
+## Session recovery: what each backend can do
 
-| | kiro-cli | claude-code |
-|---|---|---|
-| Store | `~/.kiro/sessions/cli/<uuid>.json` | `~/.claude/projects/<path-encoded>/*.jsonl` |
-| Reload | `/chat load <file>` | `--continue` / `--resume <id>` |
+Verified by running each one, not read from docs.
 
-`<path-encoded>` = absolute cwd with `/` → `-`.
+| Backend | List all sessions | Restore a *specific* session | Read summary only |
+|---|---|---|---|
+| **kiro-cli** | ✅ `conversations_v2` | ✅ export → `/chat load` | ✅ `latest_summary` |
+| **grok** | ✅ `session_search.sqlite` (FTS5) | ✅ `grok --resume <id>` | ✅ `summary.json` |
+| **claude-code** | ✅ list `*.jsonl` in project dir | ✅ `claude -r <id>` | ✅ `ai-title` line |
+| **codex** | ⚠️ no index — parse rollout files | ✅ `codex exec resume <id>` | ❌ must parse the rollout |
+| **antigravity** | ❌ index covers ~23%, 2 months stale | ✅ `agy --conversation <id>` | ⚠️ `title` empty, use `preview` |
+
+**Restoring a specific session is a manual operator action, not an AgEnD feature.** AgEnD always launches a backend on its *most recent* session (`--continue` / `--last` / `--resume`). To reach any other session someone must drive the pane or the CLI by hand.
+
+**kiro is the exception worth knowing:** its export → `/chat load` works on a **live, idle instance** with no restart. Every other backend needs the instance stopped (or the CLI run manually) because the session is chosen by a launch flag.
+
+## Safety — applies to every backend below
+
+1. **Reads are read-only.** Open SQLite with `readonly` and never write to these databases; they belong to a running CLI, and the `-wal`/`-shm` files are live.
+2. **Restore through the CLI's own mechanism** — a resume flag, or kiro's `/chat load`. Never edit a session DB or JSONL to "fix" a conversation.
+3. **Confirm the target instance is idle first** (tmux shows the ready prompt). Restoring into a working pane interrupts a turn.
+4. Nothing here needs `sudo` or touches another user's files.
+
+---
+
+## kiro-cli
+
+- **Store:** `~/.kiro/sessions/cli/<uuid>.json`
+- **DB:** `~/.local/share/kiro-cli/data.sqlite3`, table `conversations_v2`
+  - `key` — the instance's working directory
+  - `conversation_id` — session ID
+  - `value` — full session state JSON (**same format as `/chat save`**)
+  - `created_at` / `updated_at` — epoch ms
+
+**List sessions for an instance**
+```python
+import sqlite3, os
+db = os.path.expanduser('~/.local/share/kiro-cli/data.sqlite3')
+cur = sqlite3.connect(f'file:{db}?mode=ro', uri=True).cursor()
+cur.execute(
+    "SELECT conversation_id, updated_at FROM conversations_v2 WHERE key LIKE ? ORDER BY updated_at DESC LIMIT 5",
+    ('%<instance-name>%',)
+)
+# Most recent = currently active. De-duplicate by conversation_id.
+```
+
+**Restore (works on a live idle instance — no restart)**
+```python
+cur.execute("SELECT value FROM conversations_v2 WHERE conversation_id = ?", (target_cid,))
+open('<instance-workspace>/restore.json', 'w').write(cur.fetchone()[0])
+```
+```bash
+tmux send-keys -t agend:<instance> '/chat load restore.json' Enter
+# Success: "✔ Imported chat session state", context % jumps up
+```
+
+**Summary without restoring:** the session JSON has `latest_summary` (list; `[1]` is the text) and `history`.
+
+---
+
+## grok
+
+The most capable backend here. It also ships its own manual at `~/.grok/docs/user-guide/17-sessions.md`.
+
+- **Store:** `~/.grok/sessions/<URL-encoded cwd>/<session-id>/`
+  - `summary.json` — index entry: summary, timestamps, model, message counts
+  - `updates.jsonl` — the authoritative conversation log that drives resume
+  - also `chat_history.jsonl`, `plan.json`, `rewind_points.jsonl`, `signals.json`
+- **Index:** `~/.grok/sessions/session_search.sqlite` → `session_docs(session_id, cwd, updated_at, title, content)` plus a `session_docs_fts` FTS5 table, so you can full-text search past conversations.
+
+**List / search**
+```python
+import sqlite3, os
+db = os.path.expanduser('~/.grok/sessions/session_search.sqlite')
+cur = sqlite3.connect(f'file:{db}?mode=ro', uri=True).cursor()
+cur.execute("SELECT session_id, title, updated_at FROM session_docs ORDER BY updated_at DESC LIMIT 10")
+# Full-text over conversation content:
+cur.execute("SELECT session_id FROM session_docs_fts WHERE session_docs_fts MATCH ?", ('deploy',))
+```
+
+**Restore:** `grok --resume <session-id-or-title>` (a UUID is always treated as an ID; anything else matches a title in the current directory). Bare `grok --resume` takes the most recent for that cwd. In the TUI, `/resume` opens a picker that searches conversation content as you type.
+
+**Summary without restoring:** read `summary.json` directly.
+
+> ⚠️ **Titles can be ours, not the user's.** Grok auto-titles from the first prompt, and AgEnD sometimes injects a session snapshot as that first prompt — so a title may read `[system:session-snapshot] ## Previous session…`. Filter that prefix before showing titles to a user, and fall back to `updated_at` + message count.
+
+---
+
+## claude-code
+
+- **Store:** `~/.claude/projects/<path-encoded>/<session-uuid>.jsonl` — **the filename is the session ID**.
+- `<path-encoded>` = the absolute cwd with every `/` replaced by `-`.
+
+**List sessions for an instance**
+```bash
+enc=$(echo "<instance-working-dir>" | sed 's|/|-|g')
+ls -t ~/.claude/projects/"$enc"/*.jsonl        # newest first; basename = session id
+```
+
+**Summary without restoring** — the transcript contains auto-title lines; take the last one:
+```bash
+grep -h '"type":"ai-title"' <file>.jsonl | tail -1
+# {"type":"ai-title","aiTitle":"Review updated instructions","sessionId":"..."}
+```
+A session with no `ai-title` line is simply untitled — say so rather than inventing a label.
+
+**Restore:** `claude -r <session-id>` (or `claude --resume` for a picker that accepts a search term). `-c` / `--continue` takes the most recent for the cwd — that is what AgEnD launches with.
+
+> ⚠️ **Check the ID exists before using it.** AgEnD guards `--continue` precisely because resuming a session that isn't there sends claude into a restart loop. Confirm the `<id>.jsonl` file is present in the encoded project dir first.
+
+---
+
+## codex
+
+Restoring works well; **listing is the weak part — there is no index table.**
+
+- **Store:** `~/.codex/sessions/YYYY/MM/DD/rollout-<timestamp>-<uuid>.jsonl`
+- Line 0 of every rollout is the header:
+  `{"type":"session_meta","payload":{"session_id":…,"cwd":…,"timestamp":…}}`
+
+**List sessions for a working directory** — walk the tree and read only the first line of each file:
+```python
+import json, os, pathlib
+root = pathlib.Path(os.path.expanduser('~/.codex/sessions'))
+want = '<instance-working-dir>'
+out = []
+for p in root.rglob('*.jsonl'):
+    try:
+        head = json.loads(p.open(encoding='utf-8').readline())
+    except Exception:
+        continue
+    if head.get('type') == 'session_meta' and head['payload'].get('cwd') == want:
+        out.append((head['payload']['timestamp'], head['payload']['session_id']))
+for ts, sid in sorted(out, reverse=True):
+    print(ts, sid)
+```
+It opens many files, but only one line each, so it stays cheap.
+
+**Restore:** `codex exec resume <session-id> "<prompt>"` non-interactively, or `codex resume <session-id>` for the TUI (bare `codex resume` opens a picker). `codex resume --last` is what AgEnD launches with. The ID argument also accepts a session *name*.
+
+**Summary:** ❌ none available without parsing. `session_meta` carries only id/cwd/timestamp; to describe a session you must read further `event_msg` lines. Tell the user the timestamp and let them pick, rather than guessing at a topic.
+
+---
+
+## antigravity (agy)
+
+Restore is reliable; **the session list is not — do not present it as complete.**
+
+- **Store:** `~/.gemini/antigravity-cli/conversations/<uuid>.db` — one SQLite database per conversation.
+- **Index:** `~/.gemini/antigravity-cli/conversation_summaries.db`, table `conversation_summaries`
+  (`conversation_id`, `title`, `preview`, `step_count`, `last_modified_time`, `workspace_uris`, …)
+
+**List (with the caveat below)**
+```python
+import sqlite3, os
+db = os.path.expanduser('~/.gemini/antigravity-cli/conversation_summaries.db')
+cur = sqlite3.connect(f'file:{db}?mode=ro', uri=True).cursor()
+cur.execute("SELECT conversation_id, preview, step_count, last_modified_time "
+            "FROM conversation_summaries ORDER BY last_modified_time DESC")
+```
+
+**Restore:** `agy --conversation <conversation-id>`. Verified: it loads the full prior conversation, not just a stub. `-c` / `--continue` takes the most recent — that is what AgEnD launches with.
+
+> ⚠️ **The index is badly incomplete.** Measured on a live machine: 31 conversation databases on disk but only 14 index rows, of which just **7** matched a real conversation — about 23% coverage — and the newest row was **two months old**. Whatever you list, say plainly that it is a partial view and that older or recent conversations may be missing entirely. If the user knows a conversation ID, `--conversation` still works even when the index does not show it.
+>
+> ⚠️ **`title` is empty in practice** — use `preview` (the first user message) as the label, plus `step_count` for size.
+>
+> ⚠️ **`agy -p` (print mode) records nothing.** A non-interactive run leaves no conversation behind, so don't expect one to show up afterwards.
+
+---
 
 ## Fork (source must be 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`)
+- **claude-code:** copy the newest `*.jsonl` into the target's encoded project dir → start (uses `--continue`)
+- **grok:** `/fork` inside the TUI branches the conversation into a peer session
 - Prefer `replace_instance` when the whole session is poisoned (see instance-lifecycle)

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