From 194d6bd2e1a9e63b4457ef1e41dbfdcfa4e1edab Mon Sep 17 00:00:00 2001
From: Sebastian B <sb@wmc.sh>
Date: Wed, 29 Jul 2026 22:52:04 +0100
Subject: [PATCH 1/3] feat(tui): show the bound model in background subagent
 start entries

Background spawns append their started/completed/failed transcript entry
synchronously from subagent.spawned, which carries the bound model alias
on the v2 engine. Resolve it through modelDisplayName and render it in
the headline: 'coder agent (GLM 5.2) started in background'. v1 spawns
carry no model on the event, so their entries render unchanged.
---
 .../tui/controllers/subagent-event-handler.ts |  4 +++
 apps/kimi-code/src/tui/types.ts               |  2 ++
 .../src/tui/utils/background-agent-status.ts  |  8 +++---
 .../messages/background-agent-status.test.ts  | 26 +++++++++++++++++++
 4 files changed, 37 insertions(+), 3 deletions(-)

diff --git a/apps/kimi-code/src/tui/controllers/subagent-event-handler.ts b/apps/kimi-code/src/tui/controllers/subagent-event-handler.ts
index d632b50288..0982d02678 100644
--- a/apps/kimi-code/src/tui/controllers/subagent-event-handler.ts
+++ b/apps/kimi-code/src/tui/controllers/subagent-event-handler.ts
@@ -384,6 +384,10 @@ export class SubAgentEventHandler {
       parentToolCallId: event.parentToolCallId,
       agentName: event.subagentName,
       description: typeof description === 'string' ? description : undefined,
+      model:
+        event.model === undefined
+          ? undefined
+          : modelDisplayName(event.model, this.host.state.appState.availableModels[event.model]),
     };
   }
 
diff --git a/apps/kimi-code/src/tui/types.ts b/apps/kimi-code/src/tui/types.ts
index 30de918e31..f2cfda98d9 100644
--- a/apps/kimi-code/src/tui/types.ts
+++ b/apps/kimi-code/src/tui/types.ts
@@ -119,6 +119,8 @@ export interface BackgroundAgentMetadata {
   readonly parentToolCallId: string;
   readonly agentName?: string;
   readonly description?: string;
+  /** Display name of the model bound to the subagent (v2 spawns only). */
+  readonly model?: string;
 }
 
 export type BackgroundAgentStatusPhase = 'started' | 'completed' | 'failed';
diff --git a/apps/kimi-code/src/tui/utils/background-agent-status.ts b/apps/kimi-code/src/tui/utils/background-agent-status.ts
index a54257a971..015dcf1b94 100644
--- a/apps/kimi-code/src/tui/utils/background-agent-status.ts
+++ b/apps/kimi-code/src/tui/utils/background-agent-status.ts
@@ -21,12 +21,14 @@ export function formatBackgroundAgentTranscript(
 ): BackgroundAgentStatusData {
   const normalizedAgentName = normalizeBackgroundField(meta.agentName);
   const subject = normalizedAgentName !== undefined ? `${normalizedAgentName} agent` : 'agent';
+  const model = normalizeBackgroundField(meta.model);
+  const subjectWithModel = model === undefined ? subject : `${subject} (${model})`;
   const headline =
     phase === 'started'
-      ? `${subject} started in background`
+      ? `${subjectWithModel} started in background`
       : phase === 'completed'
-        ? `${subject} completed in background`
-        : `${subject} failed in background`;
+        ? `${subjectWithModel} completed in background`
+        : `${subjectWithModel} failed in background`;
   const tail = phase === 'failed' ? normalizeBackgroundField(extras?.error) : undefined;
   const detailParts = [normalizeBackgroundField(meta.description), tail].filter(
     (part): part is string => part !== undefined,
diff --git a/apps/kimi-code/test/tui/components/messages/background-agent-status.test.ts b/apps/kimi-code/test/tui/components/messages/background-agent-status.test.ts
index e8f395ec87..67f13e7507 100644
--- a/apps/kimi-code/test/tui/components/messages/background-agent-status.test.ts
+++ b/apps/kimi-code/test/tui/components/messages/background-agent-status.test.ts
@@ -3,11 +3,37 @@ import { describe, expect, it } from 'vitest';
 
 import { BackgroundAgentStatusComponent } from '#/tui/components/messages/background-agent-status';
 import { STATUS_BULLET } from '#/tui/constant/symbols';
+import { formatBackgroundAgentTranscript } from '#/tui/utils/background-agent-status';
 
 function strip(text: string): string {
   return text.replaceAll(/\u001B\[[0-9;]*m/g, '');
 }
 
+describe('formatBackgroundAgentTranscript', () => {
+  it('includes the bound model in the headline when known', () => {
+    const status = formatBackgroundAgentTranscript('started', {
+      agentId: 'agent-1',
+      parentToolCallId: 'call-1',
+      agentName: 'coder',
+      description: 'Implement the fix',
+      model: 'GLM 5.2',
+    });
+
+    expect(status.headline).toBe('coder agent (GLM 5.2) started in background');
+    expect(status.detail).toBe('Implement the fix');
+  });
+
+  it('falls back to the plain headline when the model is unknown', () => {
+    const status = formatBackgroundAgentTranscript('started', {
+      agentId: 'agent-1',
+      parentToolCallId: 'call-1',
+      agentName: 'coder',
+    });
+
+    expect(status.headline).toBe('coder agent started in background');
+  });
+});
+
 describe('BackgroundAgentStatusComponent', () => {
   it('renders started/completed with the shared bullet and failed with a red x marker', () => {
     const started = new BackgroundAgentStatusComponent({

From 9b6fdf4a58a629369eef7d1fefa2945a2677159d Mon Sep 17 00:00:00 2001
From: Sebastian B <sb@wmc.sh>
Date: Wed, 29 Jul 2026 22:52:04 +0100
Subject: [PATCH 2/3] fix(agent-core): support wire protocol 1.5 in the v1
 engine

agent-core-v2 bumped the wire protocol to 1.5 (upstream #1695), so
sessions written through kap-server / kimi web replayed in the v1 TUI
with a 'newer than the current version 1.4' warning and no migration.
Port the engine-agnostic 1.4 to 1.5 migration (backfill the goal
wall-clock anchor from the record timestamp) into agent-core and bump
AGENT_WIRE_PROTOCOL_VERSION to 1.5, matching upstream v2.
---
 .../src/agent/records/migration/index.ts      |  4 +-
 .../src/agent/records/migration/v1.5.ts       | 32 +++++++++
 .../test/agent/records/migration/v1.4.test.ts |  2 +-
 .../test/agent/records/migration/v1.5.test.ts | 69 +++++++++++++++++++
 4 files changed, 105 insertions(+), 2 deletions(-)
 create mode 100644 packages/agent-core/src/agent/records/migration/v1.5.ts
 create mode 100644 packages/agent-core/test/agent/records/migration/v1.5.test.ts

diff --git a/packages/agent-core/src/agent/records/migration/index.ts b/packages/agent-core/src/agent/records/migration/index.ts
index 8431c16329..2d12e951b8 100644
--- a/packages/agent-core/src/agent/records/migration/index.ts
+++ b/packages/agent-core/src/agent/records/migration/index.ts
@@ -2,13 +2,14 @@ import { migrateV1_0ToV1_1 } from './v1.1';
 import { migrateV1_1ToV1_2 } from './v1.2';
 import { migrateV1_2ToV1_3 } from './v1.3';
 import { migrateV1_3ToV1_4 } from './v1.4';
+import { migrateV1_4ToV1_5 } from './v1.5';
 
 // Wire protocol versions currently support only the `number.number` format.
 // Bump this only for changes that require migration of existing records or
 // change how existing records must be interpreted. Do not bump it only because
 // a new feature adds a new wire record type: older versions do not implement
 // that feature and do not need to understand the new record type.
-export const AGENT_WIRE_PROTOCOL_VERSION = '1.4';
+export const AGENT_WIRE_PROTOCOL_VERSION = '1.5';
 
 export interface WireMigrationRecord {
   readonly type: string;
@@ -26,6 +27,7 @@ const MIGRATIONS: readonly WireMigration[] = [
   migrateV1_1ToV1_2,
   migrateV1_2ToV1_3,
   migrateV1_3ToV1_4,
+  migrateV1_4ToV1_5,
 ];
 
 export function isNewerWireVersion(readVersion: string): boolean {
diff --git a/packages/agent-core/src/agent/records/migration/v1.5.ts b/packages/agent-core/src/agent/records/migration/v1.5.ts
new file mode 100644
index 0000000000..34392f2985
--- /dev/null
+++ b/packages/agent-core/src/agent/records/migration/v1.5.ts
@@ -0,0 +1,32 @@
+/**
+ * Wire protocol 1.5 persists an epoch-ms anchor at every goal create/resume
+ * boundary and wall-clock checkpoint. Version 1.4 records already carry an
+ * epoch-ms `time`, so the migration can recover that boundary without
+ * inventing a crash timestamp or adding periodic checkpoint writes. Existing
+ * anchors are authoritative.
+ *
+ * Ported from agent-core-v2 (`wire/migration/v1.5.ts`) so the v1 engine can
+ * resume v2-written 1.5 sessions natively instead of replaying them without
+ * migration.
+ */
+import type { WireMigration, WireMigrationRecord } from './index';
+
+export const migrateV1_4ToV1_5: WireMigration = {
+  sourceVersion: '1.4',
+  targetVersion: '1.5',
+  migrateRecord(record: WireMigrationRecord): WireMigrationRecord {
+    if (!advancesActiveInterval(record)) return record;
+    if (record['wallClockResumedAt'] !== undefined) return record;
+    if (typeof record['time'] !== 'number') return record;
+    return { ...record, wallClockResumedAt: record['time'] };
+  },
+};
+
+function advancesActiveInterval(record: WireMigrationRecord): boolean {
+  return (
+    record.type === 'goal.create' ||
+    (record.type === 'goal.update' &&
+      (record['status'] === 'active' ||
+        (record['status'] === undefined && typeof record['wallClockMs'] === 'number')))
+  );
+}
diff --git a/packages/agent-core/test/agent/records/migration/v1.4.test.ts b/packages/agent-core/test/agent/records/migration/v1.4.test.ts
index e5e4ae0b60..c7e59bd82d 100644
--- a/packages/agent-core/test/agent/records/migration/v1.4.test.ts
+++ b/packages/agent-core/test/agent/records/migration/v1.4.test.ts
@@ -64,7 +64,7 @@ describe('1.3 to 1.4', () => {
         },
       ]),
     ).toMatchInlineSnapshot(`
-      [wire] metadata      { "protocol_version": "<protocol-version>", "created_at": "<time>" }
+      [wire] metadata      { "protocol_version": "1.4", "created_at": "<time>" }
       [wire] goal.create   { "goalId": "goal-1", "objective": "ship the feature", "completionCriterion": "tests pass", "time": "<time>" }
       [wire] goal.update   { "tokensUsed": 5, "wallClockMs": 0, "time": "<time>" }
       [wire] goal.update   { "turnsUsed": 1, "time": "<time>" }
diff --git a/packages/agent-core/test/agent/records/migration/v1.5.test.ts b/packages/agent-core/test/agent/records/migration/v1.5.test.ts
new file mode 100644
index 0000000000..fcfc520aee
--- /dev/null
+++ b/packages/agent-core/test/agent/records/migration/v1.5.test.ts
@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+
+import { migrateV1_4ToV1_5 } from '../../../../src/agent/records/migration/v1.5';
+import { runMigration } from './utils';
+
+describe('1.4 to 1.5 active wall-clock anchor migration', () => {
+  it('backfills missing anchors from create and resume record timestamps', () => {
+    expect(
+      runMigration(migrateV1_4ToV1_5, [
+        {
+          type: 'metadata',
+          protocol_version: '1.4',
+          created_at: 1,
+        },
+        {
+          type: 'goal.create',
+          goalId: 'goal-1',
+          objective: 'ship the feature',
+          time: 10,
+        },
+        {
+          type: 'goal.update',
+          status: 'paused',
+          wallClockMs: 20,
+          time: 30,
+        },
+        {
+          type: 'goal.update',
+          status: 'active',
+          time: 40,
+        },
+      ]),
+    ).toMatchInlineSnapshot(`
+      [wire] metadata      { "protocol_version": "<protocol-version>", "created_at": "<time>" }
+      [wire] goal.create   { "goalId": "goal-1", "objective": "ship the feature", "time": "<time>", "wallClockResumedAt": 10 }
+      [wire] goal.update   { "status": "paused", "wallClockMs": 20, "time": "<time>" }
+      [wire] goal.update   { "status": "active", "time": "<time>", "wallClockResumedAt": 40 }
+    `);
+  });
+
+  it('preserves an existing active wall-clock anchor', () => {
+    expect(
+      runMigration(migrateV1_4ToV1_5, [
+        {
+          type: 'goal.update',
+          status: 'active',
+          wallClockResumedAt: 35,
+          time: 40,
+        },
+      ]),
+    ).toMatchInlineSnapshot(
+      `[wire] goal.update   { "status": "active", "wallClockResumedAt": 35, "time": "<time>" }`,
+    );
+  });
+
+  it('advances a missing anchor from a wall-clock checkpoint timestamp', () => {
+    expect(
+      runMigration(migrateV1_4ToV1_5, [
+        {
+          type: 'goal.update',
+          wallClockMs: 3_000,
+          time: 4_000,
+        },
+      ]),
+    ).toMatchInlineSnapshot(
+      `[wire] goal.update   { "wallClockMs": 3000, "time": "<time>", "wallClockResumedAt": 4000 }`,
+    );
+  });
+});

From 4ee807f4c35773a1e0991fa388a702bba8a919b0 Mon Sep 17 00:00:00 2001
From: Sebastian B <sb@wmc.sh>
Date: Wed, 29 Jul 2026 22:52:04 +0100
Subject: [PATCH 3/3] docs: condense the root AGENTS.md project map
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Project Map section grew to 17.7 KB of the 25 KB root AGENTS.md,
against the file's own rule to stay limited to hot-path rules — and it
single-handedly pushed the merged AGENTS.md prompt context past the
recommended 32 KB budget. Move the detailed per-package prose into
package-local AGENTS.md files (kap-server, transcript, minidb,
tree-sitter-bash, kimi-inspect; two facts merged into klient's) and
leave 1-2-sentence pointers in the root map (17.7 KB -> 2.9 KB, root
file 25.2 KB -> 10.3 KB). Also drops one stale fact: the root kimi-web
entry referenced a pnpm dev:v1 script that no longer exists.
---
 AGENTS.md                           | 14 ++++-----
 apps/kimi-inspect/AGENTS.md         | 46 +++++++++++++++++++++++++++++
 packages/kap-server/AGENTS.md       | 45 ++++++++++++++++++++++++++++
 packages/klient/AGENTS.md           | 10 ++++---
 packages/minidb/AGENTS.md           | 14 +++++++++
 packages/transcript/AGENTS.md       | 23 +++++++++++++++
 packages/tree-sitter-bash/AGENTS.md | 15 ++++++++++
 7 files changed, 156 insertions(+), 11 deletions(-)
 create mode 100644 apps/kimi-inspect/AGENTS.md
 create mode 100644 packages/kap-server/AGENTS.md
 create mode 100644 packages/minidb/AGENTS.md
 create mode 100644 packages/transcript/AGENTS.md
 create mode 100644 packages/tree-sitter-bash/AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
index e6fe240464..be634109ab 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -15,21 +15,21 @@ This is a TypeScript monorepo built for agent-assisted development. Keep the roo
 ## Project Map
 
 - `apps/kimi-code`: the CLI / TUI application. It consumes core capabilities through `@moonshot-ai/kimi-code-sdk` and must not depend directly on `@moonshot-ai/agent-core`. When writing or modifying its terminal UI, use the `write-tui` skill (`.agents/skills/write-tui/SKILL.md`).
-- `apps/kimi-web`: the browser web UI, a peer to the TUI. Vue 3 + Vite + vue-i18n; talks to the server over REST + WebSocket under `/api/v1`. It must not depend on `@moonshot-ai/agent-core` (wire types are re-implemented locally). Debug against the two engines via the root `pnpm dev:v1` / `pnpm dev:v2` backend scripts — the dev Sidebar shows the active backend and switches it at runtime. See `apps/kimi-web/AGENTS.md`.
+- `apps/kimi-web`: the browser web UI, a peer to the TUI (Vue 3 + Vite + vue-i18n; talks to the server over REST + WebSocket under `/api/v1`; must not depend on `@moonshot-ai/agent-core`). Architecture, design system, and dev-backend details: `apps/kimi-web/AGENTS.md`.
 - `apps/vis`, `apps/vis/server`, `apps/vis/web`: visual debugging tools for sessions and replays.
-- `apps/kimi-inspect`: web inspector for the kap-server `/api/v1/debug` RPC surface — workspace/session browser, per-session chat, and Service panels (data + trigger buttons) for the Session and Agent scopes. A left icon rail (`src/components/NavRail.tsx`) switches top-level views: the Chat workspace, the global message search (`src/components/SearchView.tsx` — cross-session full-text search over `POST /api/v1/search`, cursor-paged via a manual Load more; an exact-match checkbox maps to the API's `mode: 'literal'` substring search, which ignores sort and orders newest-first; a `live`/`index` badge on the results shows which server route served them (in-memory session transcript vs the persisted index)), the Model Catalog (`src/components/ModelCatalogView.tsx` — every Provider with its Models and the default marker, via `IModelCatalog` / `IModelService` channel proxies), and App Services (`src/components/AppServicesView.tsx` — the app-scope Service reflection, full width; the Agent scope stays in the Chat view's right dock (`src/components/RightPanel.tsx`) across two tabs: the `Agent` tab (`Inspector`: agent switcher + a Plan lookup card — `PlanCard` in `src/components/Inspector.tsx` — querying `GET /sessions/{id}/transcript/plan` (one tool_call_id, or every plan of the agent) via `src/transcript/api.ts`'s `fetchTranscriptPlan` — plus the agent Service panels) and the `State` tab (every key an Agent Service registered into the agent-state container, polled live via `IAgentStateService.snapshot()` — the same live diff-tree view as the session State tab, sharing `StateCard` from `src/components/StateCard.tsx`), while the Session scope has its own column right next to the session-list sidebar (`src/components/SessionPane.tsx`) with two tabs: Services (the pending-interactions card — `src/components/InteractionsCard.tsx` — plus the session Service panels) and State (every key a Session Service registered into the session-state container, read on demand via `ISessionStateService.snapshot()`)). Expanding a Model opens the model inspector inside that view: provider/model config layers plus the resolved runtime view with per-value provenance (config / override / builtin / env / synthesized), served on demand by `IModelCatalog.inspect` — the same resolution pass the runtime's `get` serves, traced via `ResolutionTraceCollector` and assembled by `kosong/model/inspection.ts`. Built on its own old-klient-style channel layer (`src/channel/`: the VS Code `ProxyChannel` model — service-bound `IChannel`, HTTP `ProxyChannel` for calls routed to `/api/v1/debug`), typed by `agent-core-v2` Service interfaces; `GET /api/v1/debug/channels` loads the whole wire protocol 1:1 (every scoped Service, no whitelist). There is no Service-event push channel: panels fetch/refresh on demand (`Sidebar` polls react-query on a 15 s interval), and a connection failure shows a blocking "Debug surface unavailable" screen instead of falling back anywhere. Session-level coarse status is the one exception: `src/activity/` holds a second `/api/v1/ws` client (`GlobalEventsWs`) that subscribes to nothing and consumes the server-pushed global facts — `event.session.work_changed` updates a per-session activity map (`SessionActivityHub` + subscribe/version store, seeded on connect/reconnect from `GET /api/v1/sessions`), while `event.session.created` / `session.meta.updated` invalidate the `['sessions']` query; the `Sidebar` session rows render `running` / `approval` / `question` / `failed` badges from it via `useSessionActivities`. The Vite dev server proxies `/api` to a running kap-server (`KIMI_SERVER_URL`, default `http://127.0.0.1:58627`) and exposes `GET /__inspect/servers` (`vite/serverDiscovery.ts`), which scans the local kap-server instance registry (`~/.kimi-code/server/instances` + legacy `lock`) and the home token so the app can zero-config auto-connect and switch servers from the header dropdown at runtime. The per-session chat (`src/components/ChatView.tsx`) renders turn-granularly from the **transcript** surface instead of context memory and carries an in-chat search bar (`src/components/ChatSearchBar.tsx`): it searches the current session via `POST /api/v1/search` with `container: { session_id }` (usually served by the live route, since selecting a session resumes it), and a result click funnels through the app shell's `openSearchHit` — the same agent-switch + `ChatJump` (page-back, scroll, flash) path the global search view uses; full state is read from `GET /api/v1/sessions/{id}/transcript` (initial load = newest page, refreshes re-read from the tail backwards), older history auto-pages with `before_turn` via an IntersectionObserver sentinel at the top of the scroll view, and each timeline item is wrapped in `content-visibility: auto` + `contain-intrinsic-size` so the browser virtualizes off-screen rendering natively (no windowing library); `/api/v1/ws` is an incremental channel (`transcript.ops`, grade `block` — the cheapest grade that still carries whole-state frame upserts, dropping per-token `append` frames; `transcript.reset` is ignored by the store, surfaced only to the audit recorder via the optional `onReset` handler). The channel tracks the op-batch watermark: a dedicated `subscribe_v2` control frame carries the per-agent grades and the `transcript_since` cursor, a seq gap / reconnect / `resync_required` / append gap triggers a point-to-point catch-up (`fetchTranscriptOps` → `GET .../transcript/ops?since_seq=`), and any legacy/incomplete answer falls back to the full REST refresh. Convergence reuses `@moonshot-ai/transcript`'s L2 reducer (`src/transcript/`: REST/WS clients + store; the data model and reducer come from the package, nothing is re-implemented locally). The Transcript audit panel (`src/components/audit/`, the `Audit` tab of the chat view's right dock — `src/components/RightPanel.tsx`, fed the trail by `ChatView`'s `onTrailChange`) replays how the visible store was built: an `AuditTrail` (`src/audit/`) records every step — each REST page (request + replace/prepend), every WS frame (`transcript.ops` live/buffered/flushed/catchup, `transcript.reset`), loss signals, and prompt/cancel actions — with the resulting immutable `AgentState` per entry; the panel offers a draggable timeline plus a Diff tab (structural diff vs the previous entry: added/modified/removed colored, long strings tail-truncated, all fields kept), a full State view, and the raw Event payload.
+- `apps/kimi-inspect`: web inspector for the kap-server `/api/v1/debug` RPC surface — workspace/session browser, per-session chat over the transcript surface, Service panels, global search, and model catalog. Architecture details: `apps/kimi-inspect/AGENTS.md`.
 - `packages/agent-core`: the unified agent engine, including Agent, Session, profile, skills, tools, plan, permission, background, records, the in-process DI service layer (`src/services/`), and other core capabilities.
 - `packages/node-sdk`: the public TypeScript SDK and harness.
 - `packages/kosong`: the LLM / provider abstraction layer.
 - `packages/kaos`: the execution environment and file/process abstractions.
 - `packages/oauth`: Kimi OAuth and managed auth utilities.
 - `packages/telemetry`: shared client-side telemetry infrastructure.
-- `packages/transcript`: the isomorphic transcript rendering data layer — agent-granular L1 store, idempotent L2 operations, `off/turn/block/delta` L3 subscription granularity, framework-free L4 view registry, and turn-cursor pagination. Pure TypeScript (browser-safe, no engine imports) and the sole owner of all transcript contract types (`src/contract/`); consumed by `packages/kap-server` (engine events → transcript, REST + WS surface; live stores backfill history from the persisted per-agent wire records — main on first attach, any agent on demand, cold sessions rebuild any agent — with 0-based turn ordinals matching the engine's). The cold rebuild is a two-level fold over `wire.jsonl` as the single source of truth: `history/groupTurns.ts` (context messages → turn tree) plus `history/foldFacts.ts` (non-context records → tasks, interactions, todos, goal/plan/swarm meta, and end-appended markers/taskrefs; interactions left pending at shutdown fold to `cancelled`). Plan content is a recorded fact too: each ExitPlanMode review submission offloads the document to `agents/<agentId>/plan/<planId>/v<N>.md` and persists a reference-only `plan.revision` record (`{id, version, path, sha256, bytes}`), which projects — live and cold — to a `plan.revision` marker and the `modes.plan` badge (`{reviewPath, version}`). It also owns the op-batch sequencing contract (`transcriptSeqSchema` in `contract/schema.ts`): a per-(session, agent) monotonic batch `seq` on `transcript.ops` / `transcript.reset` / the REST transcript response, the `transcript_since` subscription cursor, and the `GET .../transcript/ops` catch-up response shape — every field optional so pre-seq peers fall back to loss-signal-driven refreshes. Beyond the timeline, the model carries wire-equivalent detail: steps carry `usage` / `finishReason` / `timing` (LLM latencies) / `retry` / interrupt reason, turns carry `durationMs` / `error` / `usage`, tool frames carry the streamed `inputText` and the latest `progress`, tasks carry subagent `resultSummary` / `error` / `stateReason` / `usage`, `meta.agent` mirrors the agent status slices (model / usage / context / permission / phase), a global `prompts` entity (op `prompt.upsert`) tracks the prompt queue, and `hook.result` lands as a `'hook'` marker. These live-projected fields are NOT backfilled by the cold rebuild (known limitation).
-- `packages/kap-server`: the Kimi Code server, backed by the DI × Scope agent engine (`@moonshot-ai/agent-core-v2`). Exposes sessions over REST + WebSocket (`/api/v1` + `/api/v1/ws`); bootstrapped from `src/start.ts` and consumed by `apps/kimi-code`. The RPC surface is `/api/v1/debug/*` — a reflection dispatcher over the ENTIRE scoped DI registry (every Service callable, no whitelist; `src/transport/registerDebugRoutes.ts` + `serviceDispatcherRoutes.ts`), mounted only with `--debug-endpoints` on a loopback bind and gated by the global bearer auth; repo dev scripts pass the flag. Its transcript surface implements the op-batch sequencing contract: `TranscriptService.dispatchOps` assigns every dispatched batch a per-agent consecutive `seq` and retains it in a bounded in-memory journal (`TRANSCRIPT_OPS_JOURNAL_CAPACITY`, dies with the live store); WS `transcript.ops`/`transcript.reset` payloads carry the seq/watermark, a `transcript_since` subscription cursor (carried, with the per-agent grades, by the `subscribe_v2` control frame — the only transcript subscription channel; its agent-grained counterpart `unsubscribe_v2` detaches listed agents' streams, or the whole session's when `agent_ids` is absent, letting the detached agents' legacy events flow again) replays journaled batches instead of a baseline reset when the journal covers it, and `GET /sessions/{id}/transcript/ops?since_seq=` serves point-to-point catch-up (`complete: false` = journal can't cover or session cold → caller falls back to a full refresh). Beside the paged route, `GET /sessions/{id}/transcript/plan?agent_id=[&tool_call_id=]` projects an agent's ExitPlanMode plan info (content / path / options / review outcome; `tool_call_id` narrows to one call, omitted lists every recoverable plan) from the first available fact — the linked approval interaction's persisted request display, the live tool frame's display, or the tool result output text. The baseline `transcript.reset` itself is items-empty (`TRANSCRIPT_RESET_TAIL_TURNS = 0`): it carries only global state + the watermark + `has_more_older`, because history always pages in over REST. When a WS connection subscribes to the transcript protocol (grade ≠ `off` for an agent), the broadcaster suppresses the transcript-projected `session_event` types for that connection × agent (`TRANSCRIPT_PROJECTED_EVENT_TYPES` + `suppressedByTranscript` in `sessionEventBroadcaster.ts`; cursor replay via `getBufferedSince` applies the same filter). Suppression is only a per-connection send view — the journal still records everything, and connections without transcript grades are unaffected. The session's work aggregate behind `event.session.work_changed` (`busy` / `main_turn_active` / `pending_interaction` / `last_turn_reason`) is owned by the core's `ISessionActivityView` (`sessionActivity` domain, Session scope): the broadcaster only schedules the wire emission around turn frames (`busy:false` lands after `turn.ended`), and `resolveSessionFacts` (`src/routes/sessions.ts`) reads the same view — never fold per-agent activity at the edge. Delivery split on `/api/v1/ws`: global events (`session.meta.updated` and the `event.session.*` / `event.workspace.*` / `event.config.*` families, including every activated session's `event.session.work_changed`) fan out to EVERY established connection — `WsConnectionV1` registers itself via `broadcaster.addGlobalTarget` on construction and unregisters on close — while session/agent-grained events only reach connections subscribed to that session (subject to `agent_filter` and the transcript suppression above); transcript frames are a separate channel governed by the per-agent grades alone and bypass `agent_filter` entirely. The global search surface is `POST /api/v1/search` (`src/search/` + `src/routes/search.ts`): a cross-session full-text search over user messages, assistant text, and session titles, backed by a single minidb database at `<home>/search-index` (`IGlobalSearchService`, App scope — the write-lock holder is the indexer, other processes open read-only and catch up via WAL). It serves two modes: `terms` (the default — minidb's inverted text index over ASCII words + CJK uni/bigrams, no positions, term-level AND) and `literal` (substring-exact search: a hashed 2/3-gram index supplies candidates, every candidate's text is then confirmed with `includes`, so hits carry zero false positives; literal ignores `sort` and returns newest-first, and a candidate set truncated at `LITERAL_CANDIDATE_CAP` is flagged `incomplete: 'candidate_cap'`). When `container.session_id` is provided and that session is live in this process (`TranscriptService.forSessionLive` returns a store, wired via `setLiveTranscriptSource` in `start.ts`), BOTH modes instead scan the in-memory transcript store (turn prompts + assistant text frames, history established via `whenReady`/`ensureAgentHistory`) — no index involved; terms-mode live hits are scored Σ log(1+tf) (comparable only within a route, per the `GlobalSearchSource` contract), live-route errors never fall back to the index, and the response's `source: 'live' | 'index'` field (also mixed into the page-token fingerprint, so a mid-pagination route flip invalidates the old token) tells the caller which route served the page.
-- `packages/klient`: the client SDK — a contract-driven facade over agent-core-v2 with aggregated `global.*` / `session(id).*` / `agent(id).*` methods, zod validation on every call, and klient-level typed event forwarding. Transport is chosen once at creation via subpath entry (`@moonshot-ai/klient/ipc|memory`); both return the same `Klient`. The package also hosts the e2e suites: the legacy `/api/v1` live suites (`test/e2e/legacy/`) and the docker e2e runner (`pnpm --filter @moonshot-ai/klient docker:e2e`). See `packages/klient/AGENTS.md`.
+- `packages/transcript`: the isomorphic transcript rendering data layer — L1 store, L2 operations, L3 subscription granularity, L4 view registry; sole owner of all transcript contract types (`src/contract/`). Architecture details: `packages/transcript/AGENTS.md`.
+- `packages/kap-server`: the Kimi Code server, backed by the DI × Scope agent engine (`@moonshot-ai/agent-core-v2`); exposes sessions over REST + WebSocket (`/api/v1` + `/api/v1/ws`) and is consumed by `apps/kimi-code`. Architecture details (debug RPC, transcript surface, WS delivery, search): `packages/kap-server/AGENTS.md`.
+- `packages/klient`: the client SDK — a contract-driven facade over agent-core-v2 with aggregated `global.*` / `session(id).*` / `agent(id).*` methods, zod validation on every call, and typed event forwarding; also hosts the e2e suites. Architecture and testing details: `packages/klient/AGENTS.md`.
 - `packages/server-e2e`: live e2e tests and scenarios against a running server (`KIMI_SERVER_URL`, default `http://127.0.0.1:58627`). See `packages/server-e2e/AGENTS.md`.
-- `packages/tree-sitter-bash`: a pure-TypeScript bash parser (no runtime deps, no wasm) that produces a syntax tree with tree-sitter-bash 0.25.0 named-node type names and UTF-16 code-unit offsets. `parse(source, { timeoutMs, maxNodes })` runs under a deterministic budget (default 50 ms / 50k nodes, plus per-chain recursion depth caps) and returns a discriminated `ParseResult` (`{ ok, rootNode, hasError }` or `{ ok: false, reason: 'aborted' }`) — callers must treat aborted/hasError trees as "cannot analyze" and degrade. Parser only, no safety judgments; consumers (e.g. Bash tool permission matching) live elsewhere. Known deviations from the reference are tracked in the package README's "Known differences" section, pinned by differential fixtures tested against the real `tree-sitter-bash` wasm (dev-only).
-- `packages/minidb`: the embedded JSON document store (`MiniDb`) behind kap-server's search index — snapshot + WAL persistence with an exclusive write lock (losers open read-only and catch up from the WAL), plus a larger-than-RAM full-text layer: `src/text-index.ts` is the inverted index (in-RAM dictionary + delta, on-disk postings in `src/text-postings.ts`, rebuilt from the Store on open and on compaction) with an injectable `tokenizer`/`queryTokenizer`; the default tokenizer keeps ASCII words and CJK uni/bigrams, while `src/trigram.ts` provides the hashed 2/3-gram tokenizer (NFKC + lowercase, code-point windows) that backs substring-exact search. Text-index definitions (including the tokenizer name) persist in `db.textindexes.json`.
+- `packages/tree-sitter-bash`: a pure-TypeScript bash parser (no runtime deps, no wasm) producing a tree-sitter-bash-compatible syntax tree. Parse contract and known differences: `packages/tree-sitter-bash/AGENTS.md`.
+- `packages/minidb`: the embedded JSON document store (`MiniDb`) behind kap-server's search index — snapshot + WAL persistence plus a larger-than-RAM full-text layer. Details: `packages/minidb/AGENTS.md`.
 
 ## Environment Requirements
 
diff --git a/apps/kimi-inspect/AGENTS.md b/apps/kimi-inspect/AGENTS.md
new file mode 100644
index 0000000000..a49b688512
--- /dev/null
+++ b/apps/kimi-inspect/AGENTS.md
@@ -0,0 +1,46 @@
+# kimi-inspect Agent Guide
+
+Package-local rules for `apps/kimi-inspect` (`@moonshot-ai/kimi-inspect`).
+
+## What it is
+
+Web inspector for the kap-server `/api/v1/debug` RPC surface — workspace/session browser, per-session chat, and Service panels (data + trigger buttons) for the Session and Agent scopes.
+
+## Top-level views (`src/components/NavRail.tsx`)
+
+A left icon rail switches top-level views:
+
+- **Chat workspace** — the per-session chat (see "ChatView transcript rendering" below).
+- **Global message search** (`src/components/SearchView.tsx`) — cross-session full-text search over `POST /api/v1/search`, cursor-paged via a manual Load more; an exact-match checkbox maps to the API's `mode: 'literal'` substring search, which ignores sort and orders newest-first; a `live`/`index` badge on the results shows which server route served them (in-memory session transcript vs the persisted index).
+- **Model Catalog** (`src/components/ModelCatalogView.tsx`) — every Provider with its Models and the default marker, via `IModelCatalog` / `IModelService` channel proxies. Expanding a Model opens the model inspector inside that view: provider/model config layers plus the resolved runtime view with per-value provenance (config / override / builtin / env / synthesized), served on demand by `IModelCatalog.inspect` — the same resolution pass the runtime's `get` serves, traced via `ResolutionTraceCollector` and assembled by `kosong/model/inspection.ts`.
+- **App Services** (`src/components/AppServicesView.tsx`) — the app-scope Service reflection, full width.
+
+## Scope panels
+
+- The **Agent scope** stays in the Chat view's right dock (`src/components/RightPanel.tsx`) across two tabs: the `Agent` tab (`Inspector`: agent switcher + a Plan lookup card — `PlanCard` in `src/components/Inspector.tsx` — querying `GET /sessions/{id}/transcript/plan` (one tool_call_id, or every plan of the agent) via `src/transcript/api.ts`'s `fetchTranscriptPlan` — plus the agent Service panels) and the `State` tab (every key an Agent Service registered into the agent-state container, polled live via `IAgentStateService.snapshot()` — the same live diff-tree view as the session State tab, sharing `StateCard` from `src/components/StateCard.tsx`).
+- The **Session scope** has its own column right next to the session-list sidebar (`src/components/SessionPane.tsx`) with two tabs: Services (the pending-interactions card — `src/components/InteractionsCard.tsx` — plus the session Service panels) and State (every key a Session Service registered into the session-state container, read on demand via `ISessionStateService.snapshot()`).
+
+## Channel layer
+
+Built on its own old-klient-style channel layer (`src/channel/`: the VS Code `ProxyChannel` model — service-bound `IChannel`, HTTP `ProxyChannel` for calls routed to `/api/v1/debug`), typed by `agent-core-v2` Service interfaces; `GET /api/v1/debug/channels` loads the whole wire protocol 1:1 (every scoped Service, no whitelist). There is no Service-event push channel: panels fetch/refresh on demand (`Sidebar` polls react-query on a 15 s interval), and a connection failure shows a blocking "Debug surface unavailable" screen instead of falling back anywhere.
+
+## Session activity (`src/activity/`)
+
+Session-level coarse status is the one exception to no-push: `src/activity/` holds a second `/api/v1/ws` client (`GlobalEventsWs`) that subscribes to nothing and consumes the server-pushed global facts — `event.session.work_changed` updates a per-session activity map (`SessionActivityHub` + subscribe/version store, seeded on connect/reconnect from `GET /api/v1/sessions`), while `event.session.created` / `session.meta.updated` invalidate the `['sessions']` query; the `Sidebar` session rows render `running` / `approval` / `question` / `failed` badges from it via `useSessionActivities`.
+
+## Dev server and server discovery
+
+The Vite dev server proxies `/api` to a running kap-server (`KIMI_SERVER_URL`, default `http://127.0.0.1:58627`) and exposes `GET /__inspect/servers` (`vite/serverDiscovery.ts`), which scans the local kap-server instance registry (`~/.kimi-code/server/instances` + legacy `lock`) and the home token so the app can zero-config auto-connect and switch servers from the header dropdown at runtime.
+
+## ChatView transcript rendering
+
+The per-session chat (`src/components/ChatView.tsx`) renders turn-granularly from the **transcript** surface instead of context memory:
+
+- It carries an in-chat search bar (`src/components/ChatSearchBar.tsx`): it searches the current session via `POST /api/v1/search` with `container: { session_id }` (usually served by the live route, since selecting a session resumes it), and a result click funnels through the app shell's `openSearchHit` — the same agent-switch + `ChatJump` (page-back, scroll, flash) path the global search view uses.
+- Full state is read from `GET /api/v1/sessions/{id}/transcript` (initial load = newest page, refreshes re-read from the tail backwards); older history auto-pages with `before_turn` via an IntersectionObserver sentinel at the top of the scroll view, and each timeline item is wrapped in `content-visibility: auto` + `contain-intrinsic-size` so the browser virtualizes off-screen rendering natively (no windowing library).
+- `/api/v1/ws` is an incremental channel (`transcript.ops`, grade `block` — the cheapest grade that still carries whole-state frame upserts, dropping per-token `append` frames; `transcript.reset` is ignored by the store, surfaced only to the audit recorder via the optional `onReset` handler). The channel tracks the op-batch watermark: a dedicated `subscribe_v2` control frame carries the per-agent grades and the `transcript_since` cursor, a seq gap / reconnect / `resync_required` / append gap triggers a point-to-point catch-up (`fetchTranscriptOps` → `GET .../transcript/ops?since_seq=`), and any legacy/incomplete answer falls back to the full REST refresh.
+- Convergence reuses `@moonshot-ai/transcript`'s L2 reducer (`src/transcript/`: REST/WS clients + store; the data model and reducer come from the package, nothing is re-implemented locally).
+
+## Transcript audit panel
+
+The Transcript audit panel (`src/components/audit/`, the `Audit` tab of the chat view's right dock — `src/components/RightPanel.tsx`, fed the trail by `ChatView`'s `onTrailChange`) replays how the visible store was built: an `AuditTrail` (`src/audit/`) records every step — each REST page (request + replace/prepend), every WS frame (`transcript.ops` live/buffered/flushed/catchup, `transcript.reset`), loss signals, and prompt/cancel actions — with the resulting immutable `AgentState` per entry; the panel offers a draggable timeline plus a Diff tab (structural diff vs the previous entry: added/modified/removed colored, long strings tail-truncated, all fields kept), a full State view, and the raw Event payload.
diff --git a/packages/kap-server/AGENTS.md b/packages/kap-server/AGENTS.md
new file mode 100644
index 0000000000..b71813f250
--- /dev/null
+++ b/packages/kap-server/AGENTS.md
@@ -0,0 +1,45 @@
+# kap-server Agent Guide
+
+Package-local rules for `packages/kap-server` (`@moonshot-ai/kap-server`).
+
+## What it is
+
+The Kimi Code server, backed by the DI × Scope agent engine (`@moonshot-ai/agent-core-v2`). It exposes sessions over REST + WebSocket (`/api/v1` + `/api/v1/ws`), is bootstrapped from `src/start.ts`, and is consumed by `apps/kimi-code`.
+
+## Debug RPC surface
+
+The RPC surface is `/api/v1/debug/*` — a reflection dispatcher over the ENTIRE scoped DI registry (every Service callable, no whitelist; `src/transport/registerDebugRoutes.ts` + `serviceDispatcherRoutes.ts`), mounted only with `--debug-endpoints` on a loopback bind and gated by the global bearer auth; repo dev scripts pass the flag.
+
+## Transcript surface: op-batch sequencing
+
+Its transcript surface implements the op-batch sequencing contract (owned by `@moonshot-ai/transcript`):
+
+- `TranscriptService.dispatchOps` assigns every dispatched batch a per-agent consecutive `seq` and retains it in a bounded in-memory journal (`TRANSCRIPT_OPS_JOURNAL_CAPACITY`, dies with the live store).
+- WS `transcript.ops`/`transcript.reset` payloads carry the seq/watermark.
+- A `transcript_since` subscription cursor (carried, with the per-agent grades, by the `subscribe_v2` control frame — the only transcript subscription channel; its agent-grained counterpart `unsubscribe_v2` detaches listed agents' streams, or the whole session's when `agent_ids` is absent, letting the detached agents' legacy events flow again) replays journaled batches instead of a baseline reset when the journal covers it.
+- `GET /sessions/{id}/transcript/ops?since_seq=` serves point-to-point catch-up (`complete: false` = journal can't cover or session cold → caller falls back to a full refresh).
+- Beside the paged route, `GET /sessions/{id}/transcript/plan?agent_id=[&tool_call_id=]` projects an agent's ExitPlanMode plan info (content / path / options / review outcome; `tool_call_id` narrows to one call, omitted lists every recoverable plan) from the first available fact — the linked approval interaction's persisted request display, the live tool frame's display, or the tool result output text.
+- The baseline `transcript.reset` itself is items-empty (`TRANSCRIPT_RESET_TAIL_TURNS = 0`): it carries only global state + the watermark + `has_more_older`, because history always pages in over REST.
+
+## Transcript suppression
+
+When a WS connection subscribes to the transcript protocol (grade ≠ `off` for an agent), the broadcaster suppresses the transcript-projected `session_event` types for that connection × agent (`TRANSCRIPT_PROJECTED_EVENT_TYPES` + `suppressedByTranscript` in `sessionEventBroadcaster.ts`; cursor replay via `getBufferedSince` applies the same filter). Suppression is only a per-connection send view — the journal still records everything, and connections without transcript grades are unaffected.
+
+## Session work aggregate
+
+The session's work aggregate behind `event.session.work_changed` (`busy` / `main_turn_active` / `pending_interaction` / `last_turn_reason`) is owned by the core's `ISessionActivityView` (`sessionActivity` domain, Session scope): the broadcaster only schedules the wire emission around turn frames (`busy:false` lands after `turn.ended`), and `resolveSessionFacts` (`src/routes/sessions.ts`) reads the same view — never fold per-agent activity at the edge.
+
+## WS delivery split
+
+Delivery split on `/api/v1/ws`:
+
+- Global events (`session.meta.updated` and the `event.session.*` / `event.workspace.*` / `event.config.*` families, including every activated session's `event.session.work_changed`) fan out to EVERY established connection — `WsConnectionV1` registers itself via `broadcaster.addGlobalTarget` on construction and unregisters on close.
+- Session/agent-grained events only reach connections subscribed to that session (subject to `agent_filter` and the transcript suppression above).
+- Transcript frames are a separate channel governed by the per-agent grades alone and bypass `agent_filter` entirely.
+
+## Global search surface
+
+The global search surface is `POST /api/v1/search` (`src/search/` + `src/routes/search.ts`): a cross-session full-text search over user messages, assistant text, and session titles, backed by a single minidb database at `<home>/search-index` (`IGlobalSearchService`, App scope — the write-lock holder is the indexer, other processes open read-only and catch up via WAL).
+
+- It serves two modes: `terms` (the default — minidb's inverted text index over ASCII words + CJK uni/bigrams, no positions, term-level AND) and `literal` (substring-exact search: a hashed 2/3-gram index supplies candidates, every candidate's text is then confirmed with `includes`, so hits carry zero false positives; literal ignores `sort` and returns newest-first, and a candidate set truncated at `LITERAL_CANDIDATE_CAP` is flagged `incomplete: 'candidate_cap'`).
+- When `container.session_id` is provided and that session is live in this process (`TranscriptService.forSessionLive` returns a store, wired via `setLiveTranscriptSource` in `start.ts`), BOTH modes instead scan the in-memory transcript store (turn prompts + assistant text frames, history established via `whenReady`/`ensureAgentHistory`) — no index involved; terms-mode live hits are scored Σ log(1+tf) (comparable only within a route, per the `GlobalSearchSource` contract), live-route errors never fall back to the index, and the response's `source: 'live' | 'index'` field (also mixed into the page-token fingerprint, so a mid-pagination route flip invalidates the old token) tells the caller which route served the page.
diff --git a/packages/klient/AGENTS.md b/packages/klient/AGENTS.md
index d4724f483b..42211b343c 100644
--- a/packages/klient/AGENTS.md
+++ b/packages/klient/AGENTS.md
@@ -19,10 +19,12 @@ The package is layered; keep the layers strict when changing code:
   wire's `null`-vs-`undefined` semantics — use them for every
   `X | undefined` / `void` result.
 - **Transports** (`src/transports/{ipc,memory}`) — each implements the
-  `KlientChannel` SPI (`src/core/channel.ts`) and nothing else. ipc frames
-  the same dispatcher traffic as NDJSON over a unix socket and shares the
-  in-process dispatcher with memory; memory JSON round-trips every value so
-  both transports return byte-identical data.
+  `KlientChannel` SPI (`src/core/channel.ts`) and nothing else. The transport
+  is chosen once at creation via subpath entry
+  (`@moonshot-ai/klient/ipc|memory`); both return the same `Klient`. ipc
+  frames the same dispatcher traffic as NDJSON over a unix socket and shares
+  the in-process dispatcher with memory; memory JSON round-trips every value
+  so both transports return byte-identical data.
 
 The facade only covers services that behave identically on both transports
 (the in-process dispatcher mirrors the server's scope resolution, including
diff --git a/packages/minidb/AGENTS.md b/packages/minidb/AGENTS.md
new file mode 100644
index 0000000000..bc6357c9a8
--- /dev/null
+++ b/packages/minidb/AGENTS.md
@@ -0,0 +1,14 @@
+# minidb Agent Guide
+
+Package-local rules for `packages/minidb` (`@moonshot-ai/minidb`).
+
+## What it is
+
+The embedded JSON document store (`MiniDb`) behind kap-server's search index — snapshot + WAL persistence with an exclusive write lock (losers open read-only and catch up from the WAL), plus a larger-than-RAM full-text layer.
+
+## Full-text layer
+
+- `src/text-index.ts` is the inverted index (in-RAM dictionary + delta, on-disk postings in `src/text-postings.ts`, rebuilt from the Store on open and on compaction) with an injectable `tokenizer`/`queryTokenizer`.
+- The default tokenizer keeps ASCII words and CJK uni/bigrams.
+- `src/trigram.ts` provides the hashed 2/3-gram tokenizer (NFKC + lowercase, code-point windows) that backs substring-exact search.
+- Text-index definitions (including the tokenizer name) persist in `db.textindexes.json`.
diff --git a/packages/transcript/AGENTS.md b/packages/transcript/AGENTS.md
new file mode 100644
index 0000000000..8837c09967
--- /dev/null
+++ b/packages/transcript/AGENTS.md
@@ -0,0 +1,23 @@
+# transcript Agent Guide
+
+Package-local rules for `packages/transcript` (`@moonshot-ai/transcript`).
+
+## What it is
+
+The isomorphic transcript rendering data layer — agent-granular L1 store, idempotent L2 operations, `off/turn/block/delta` L3 subscription granularity, framework-free L4 view registry, and turn-cursor pagination. Pure TypeScript (browser-safe, no engine imports) and the sole owner of all transcript contract types (`src/contract/`); consumed by `packages/kap-server` (engine events → transcript, REST + WS surface).
+
+## History backfill and cold rebuild
+
+Live stores backfill history from the persisted per-agent wire records — main on first attach, any agent on demand, cold sessions rebuild any agent — with 0-based turn ordinals matching the engine's. The cold rebuild is a two-level fold over `wire.jsonl` as the single source of truth: `history/groupTurns.ts` (context messages → turn tree) plus `history/foldFacts.ts` (non-context records → tasks, interactions, todos, goal/plan/swarm meta, and end-appended markers/taskrefs; interactions left pending at shutdown fold to `cancelled`).
+
+## Plan revisions
+
+Plan content is a recorded fact too: each ExitPlanMode review submission offloads the document to `agents/<agentId>/plan/<planId>/v<N>.md` and persists a reference-only `plan.revision` record (`{id, version, path, sha256, bytes}`), which projects — live and cold — to a `plan.revision` marker and the `modes.plan` badge (`{reviewPath, version}`).
+
+## Op-batch sequencing contract
+
+The package owns the op-batch sequencing contract (`transcriptSeqSchema` in `contract/schema.ts`): a per-(session, agent) monotonic batch `seq` on `transcript.ops` / `transcript.reset` / the REST transcript response, the `transcript_since` subscription cursor, and the `GET .../transcript/ops` catch-up response shape — every field optional so pre-seq peers fall back to loss-signal-driven refreshes.
+
+## Wire-equivalent detail (live-only fields)
+
+Beyond the timeline, the model carries wire-equivalent detail: steps carry `usage` / `finishReason` / `timing` (LLM latencies) / `retry` / interrupt reason, turns carry `durationMs` / `error` / `usage`, tool frames carry the streamed `inputText` and the latest `progress`, tasks carry subagent `resultSummary` / `error` / `stateReason` / `usage`, `meta.agent` mirrors the agent status slices (model / usage / context / permission / phase), a global `prompts` entity (op `prompt.upsert`) tracks the prompt queue, and `hook.result` lands as a `'hook'` marker. These live-projected fields are NOT backfilled by the cold rebuild (known limitation).
diff --git a/packages/tree-sitter-bash/AGENTS.md b/packages/tree-sitter-bash/AGENTS.md
new file mode 100644
index 0000000000..a497d30998
--- /dev/null
+++ b/packages/tree-sitter-bash/AGENTS.md
@@ -0,0 +1,15 @@
+# tree-sitter-bash Agent Guide
+
+Package-local rules for `packages/tree-sitter-bash` (`@moonshot-ai/tree-sitter-bash`).
+
+## What it is
+
+A pure-TypeScript bash parser (no runtime deps, no wasm) that produces a syntax tree with tree-sitter-bash 0.25.0 named-node type names and UTF-16 code-unit offsets.
+
+## Parse contract
+
+`parse(source, { timeoutMs, maxNodes })` runs under a deterministic budget (default 50 ms / 50k nodes, plus per-chain recursion depth caps) and returns a discriminated `ParseResult` (`{ ok, rootNode, hasError }` or `{ ok: false, reason: 'aborted' }`) — callers must treat aborted/hasError trees as "cannot analyze" and degrade.
+
+## Scope
+
+Parser only, no safety judgments; consumers (e.g. Bash tool permission matching) live elsewhere. Known deviations from the reference are tracked in the package README's "Known differences" section, pinned by differential fixtures tested against the real `tree-sitter-bash` wasm (dev-only).