From c0b79979bd1b13facccd763931233af97e90e685 Mon Sep 17 00:00:00 2001
From: deepagent-ai <jamessmithm539@gmail.com>
Date: Tue, 21 Jul 2026 01:22:18 +0800
Subject: [PATCH 1/5] =?UTF-8?q?perf(core):=20=E4=BF=AE=E5=A4=8D=E5=90=AF?=
 =?UTF-8?q?=E5=8A=A8=E6=85=A2=E6=A0=B9=E5=9B=A0=20=E2=80=94=20sessions.jso?=
 =?UTF-8?q?n=20=E9=98=B2=E6=8A=96=20+=20EventV2=20retention?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

**根因定位**
- `deepagent-code.db` 704MB，其中 `event` 表独占 559MB（75K 行 EventV2
  mirror 事件，无任何清理机制，只增不减）
- `sessions.json` 2.6MB，每次状态变更（28 处调用点）同步全量写入（含 fsync）
  + pretty-print 额外 25% 体积；单个 session `userRequest` 字段高达 837KB
- `import-snapshot.db` 1GB 一次性导入快照（已单独手动删除）

**Fix 1 — sessions.json（packages/core/src/deepagent/session-state.ts）**
- 去掉 `JSON.stringify(data, null, 2)` 的 pretty-print，改用紧凑 JSON
- saveToDisk 改为防抖模式：多次连续调用只触发一次 `setImmediate` 写入，
  不再每次 streaming delta 都阻塞 event loop 做 fsync
- `userRequest` 字段超过 10KB 时在序列化前截断，防止单个大粘贴
  把整个 sessions.json 膨胀数百 KB

**Fix 2 — EventV2 retention（packages/core/src/deepagent/retention-sweeper.ts）**
- 原有 RetentionSweeper 只清理 `deepagent_event`（DeepAgentEventBus），
  不碰 `event`/`event_sequence`（EventV2 mirror），导致无限增长
- 在 sweepOnce 里为每个 workspace 增加一步：查找 `session` 表中
  `time_archived IS NOT NULL AND time_archived < olderThan` 的会话，
  DELETE 其 `event_sequence` 行（CASCADE 自动清掉对应 `event` 行）
- 引用安全：只 prune 已存档且超过 retentionDays（默认30天）的会话，
  活跃会话的 event 日志完全不动
- SweepSummary 新增 `deletedEventV2Sequences` 字段用于可观测性

**测试（test/retention-sweeper.test.ts）**
- 新增3个 §EventV2-retention 测试：
  prune 超期已存档会话事件 / 保留最近存档 / 保留未存档活跃会话
- 全部 11 个 sweeper 测试通过，turbo typecheck 15/15 全绿

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../core/src/deepagent/retention-sweeper.ts   |  45 ++++++-
 packages/core/src/deepagent/session-state.ts  |  35 +++++-
 packages/core/test/retention-sweeper.test.ts  | 114 ++++++++++++++++++
 3 files changed, 191 insertions(+), 3 deletions(-)

diff --git a/packages/core/src/deepagent/retention-sweeper.ts b/packages/core/src/deepagent/retention-sweeper.ts
index 6686d9bc..5effac61 100644
--- a/packages/core/src/deepagent/retention-sweeper.ts
+++ b/packages/core/src/deepagent/retention-sweeper.ts
@@ -1,13 +1,16 @@
 export * as RetentionSweeper from "./retention-sweeper"
 
 import { Cause, Context, Duration, Effect, Layer, Schedule } from "effect"
-import { and, eq, lt } from "drizzle-orm"
+import { and, eq, isNotNull, lt } from "drizzle-orm"
 import { Database } from "../database/database"
 import { DeepAgentEventBus } from "./deepagent-event-bus"
 import { DeepAgentEventTable } from "./deepagent-event-sql"
 import { ApprovalQueueTable } from "./approval-queue-sql"
 import { WorkspaceConfig } from "./workspace-config"
 import { AgentPushLogTable } from "../im/push-log-sql"
+import { EventSequenceTable } from "../event/sql"
+import { SessionTable } from "../session/sql"
+import type { WorkspaceV2 } from "../workspace"
 import * as Log from "../util/log"
 
 // V4.0 §A3 保留期 — the periodic RETENTION SWEEPER. For each workspace that has durable events it reads
@@ -34,6 +37,9 @@ export interface SweepSummary {
   readonly deletedEvents: number
   readonly deletedPushLogs: number
   readonly deletedApprovals: number
+  // PERF: EventV2 mirror events pruned for archived sessions. Reported separately because the
+  // accounting is by aggregate (session), not individual rows, so it has different semantics.
+  readonly deletedEventV2Sequences: number
 }
 
 export interface Interface {
@@ -81,6 +87,7 @@ export const layerWith = (options?: LayerOptions) =>
           let deletedEvents = 0
           let deletedPushLogs = 0
           let deletedApprovals = 0
+          let deletedEventV2Sequences = 0
 
           for (const { workspaceID } of workspaceRows) {
             const resolved = yield* config.get(workspaceID)
@@ -119,6 +126,40 @@ export const layerWith = (options?: LayerOptions) =>
               .all()
               .pipe(Effect.orDie)
             deletedApprovals += approvalDeleted.length
+
+            // PERF §EventV2-retention: prune EventV2 mirror events for sessions that have been
+            // archived for longer than retentionDays. The EventV2 `event` table records every
+            // streaming delta (message.part.updated, etc.) and has no built-in expiry — it grows
+            // unboundedly and can reach 500MB+ on long-running deployments. Once a session is
+            // archived its event history is cold and safe to discard: active sessions keep their
+            // full event log for live projector replay, but archived ones no longer need it.
+            //
+            // Implementation: delete rows from `event_sequence` where the corresponding session row
+            // (same workspace) has time_archived IS NOT NULL AND time_archived < olderThan.
+            // The EventTable has ON DELETE CASCADE from event_sequence, so this one DELETE removes
+            // both the sequence header and all its events in a single statement.
+            const archivedSessions = yield* db
+              .select({ id: SessionTable.id })
+              .from(SessionTable)
+              .where(
+                and(
+                  eq(SessionTable.workspace_id, workspaceID as WorkspaceV2.ID),
+                  isNotNull(SessionTable.time_archived),
+                  lt(SessionTable.time_archived, olderThan),
+                ),
+              )
+              .all()
+              .pipe(Effect.orDie)
+
+            for (const { id } of archivedSessions) {
+              const seqDeleted = yield* db
+                .delete(EventSequenceTable)
+                .where(eq(EventSequenceTable.aggregate_id, id))
+                .returning({ aggregate_id: EventSequenceTable.aggregate_id })
+                .all()
+                .pipe(Effect.orDie)
+              deletedEventV2Sequences += seqDeleted.length
+            }
           }
 
           return {
@@ -126,6 +167,7 @@ export const layerWith = (options?: LayerOptions) =>
             deletedEvents,
             deletedPushLogs,
             deletedApprovals,
+            deletedEventV2Sequences,
           }
         })
 
@@ -141,6 +183,7 @@ export const layerWith = (options?: LayerOptions) =>
                   deletedEvents: 0,
                   deletedPushLogs: 0,
                   deletedApprovals: 0,
+                  deletedEventV2Sequences: 0,
                 }),
               ),
             ),
diff --git a/packages/core/src/deepagent/session-state.ts b/packages/core/src/deepagent/session-state.ts
index 0ffad154..9f0f520c 100644
--- a/packages/core/src/deepagent/session-state.ts
+++ b/packages/core/src/deepagent/session-state.ts
@@ -522,14 +522,45 @@ export const pruneCompleted = (maxAge_ms = 24 * 60 * 60 * 1000): void => {
   saveToDisk()
 }
 
+// PERF: maximum bytes stored for the userRequest field. The field is used for display/context
+// heuristics only — a 10KB cap prevents one large paste from bloating sessions.json by ~800KB.
+const MAX_USER_REQUEST_BYTES = 10_000
+
+// PERF: debounce timer handle — collapses many back-to-back saveToDisk() calls (e.g. per streaming
+// delta) into one write at the end of the current JS task. setImmediate fires after I/O callbacks
+// so the write never races with in-progress DB operations.
+let _savePending = false
+
 function saveToDisk() {
+  if (!stateDir) return
+  if (_savePending) return
+  _savePending = true
+  // Schedule the actual write after the current synchronous work finishes. This collapses N
+  // rapid-fire calls (tool result ingestion, round-control advances, plan latch flips …) into a
+  // single atomic write per event-loop turn.
+  setImmediate(flushToDisk)
+}
+
+function flushToDisk() {
+  _savePending = false
   if (!stateDir) return
   // P2-G: atomic rewrite so a crash can't truncate sessions.json. P2-D: surface write failures to
   // stderr instead of silently dropping run state (a lost session-state write is a real data loss,
   // not something to swallow). Still non-throwing: persistence failure must not crash the turn.
   try {
-    const data = Object.fromEntries(sessions)
-    writeFileAtomic(path.join(stateDir, "sessions.json"), JSON.stringify(data, null, 2))
+    // Build a serialization-safe snapshot: truncate oversized fields so one large session
+    // (e.g. a user pasting a multi-hundred-KB document) does not inflate the whole file.
+    const data: Record<string, unknown> = {}
+    for (const [id, state] of sessions) {
+      const serialized: Record<string, unknown> = { ...state }
+      if (typeof serialized.userRequest === "string" && serialized.userRequest.length > MAX_USER_REQUEST_BYTES) {
+        serialized.userRequest = serialized.userRequest.slice(0, MAX_USER_REQUEST_BYTES)
+      }
+      data[id] = serialized
+    }
+    // Compact JSON (no pretty-print): sessions.json is machine-read only; the 2-space indent
+    // was adding ~25% bloat to a file that is synchronously read and written on every state change.
+    writeFileAtomic(path.join(stateDir, "sessions.json"), JSON.stringify(data))
   } catch (error) {
     console.error("deepagent session-state: failed to persist sessions.json", error)
   }
diff --git a/packages/core/test/retention-sweeper.test.ts b/packages/core/test/retention-sweeper.test.ts
index 0585c03e..986bb4e0 100644
--- a/packages/core/test/retention-sweeper.test.ts
+++ b/packages/core/test/retention-sweeper.test.ts
@@ -8,6 +8,8 @@ import { Database } from "@deepagent-code/core/database/database"
 import { DeepAgentEventDeliveryTable } from "@deepagent-code/core/deepagent/deepagent-event-sql"
 import { ApprovalQueueTable } from "@deepagent-code/core/deepagent/approval-queue-sql"
 import { AgentPushLogTable } from "@deepagent-code/core/im/push-log-sql"
+import { EventSequenceTable, EventTable } from "@deepagent-code/core/event/sql"
+import { SessionTable } from "@deepagent-code/core/session/sql"
 import { testEffect } from "./lib/effect"
 
 // V4.0 §A3 保留期 — the retention sweep + sweeper daemon. Verifies age-based deletion, referential
@@ -301,4 +303,116 @@ describe("RetentionSweeper", () => {
       expect(logs.map((l) => l.id)).toEqual(["push_new"])
     }),
   )
+
+  // PERF §EventV2-retention: verify that EventV2 mirror events are pruned for archived sessions
+  // that exceeded retentionDays. The event table has no timestamp of its own; we use the session's
+  // time_archived as the retention anchor.
+
+  /** Insert a minimal project + session row so the event_sequence FK is satisfiable. */
+  const insertArchivedSession = (opts: { sessionID: string; workspaceID: string; timeArchived: number }) =>
+    Effect.gen(function* () {
+      const { db } = yield* Database.Service
+      yield* db
+        .run(
+          `INSERT OR IGNORE INTO project (id, worktree, sandboxes, time_created, time_updated)
+           VALUES ('proj_test', '/tmp', '[]', 0, 0)`,
+        )
+        .pipe(Effect.orDie)
+      yield* db
+        .run(
+          `INSERT OR IGNORE INTO session
+             (id, project_id, workspace_id, slug, directory, title, version, time_created, time_updated, time_archived)
+           VALUES ('${opts.sessionID}', 'proj_test', '${opts.workspaceID}', 'test',
+                   '/tmp', 'test', '1', 0, 0, ${opts.timeArchived})`,
+        )
+        .pipe(Effect.orDie)
+    })
+
+  /** Insert event_sequence + one event row for a session aggregate. */
+  const insertEventV2 = (opts: { sessionID: string; eventID: string }) =>
+    Effect.gen(function* () {
+      const { db } = yield* Database.Service
+      yield* db
+        .run(`INSERT OR IGNORE INTO event_sequence (aggregate_id, seq) VALUES ('${opts.sessionID}', 1)`)
+        .pipe(Effect.orDie)
+      yield* db
+        .run(
+          `INSERT OR IGNORE INTO event (id, aggregate_id, seq, type, data)
+           VALUES ('${opts.eventID}', '${opts.sessionID}', 1, 'message.part.updated.1', '{}')`,
+        )
+        .pipe(Effect.orDie)
+    })
+
+  it.effect("§EventV2-retention: prunes event_sequence + events for archived sessions past retentionDays", () =>
+    Effect.gen(function* () {
+      const { db } = yield* Database.Service
+      const b = yield* DeepAgentEventBus.Service
+      const c = yield* WorkspaceConfig.Service
+      const s = yield* RetentionSweeper.Service
+      yield* c.set("wrk_1", { retentionDays: 30 })
+      // Publish a DeepAgentEvent so the workspace is enumerated by the sweeper.
+      yield* publishAt(b, 1_000)
+
+      // An archived session whose time_archived is ancient (1 ms epoch = 1970).
+      yield* insertArchivedSession({ sessionID: "ses_old", workspaceID: "wrk_1", timeArchived: 1_000 })
+      yield* insertEventV2({ sessionID: "ses_old", eventID: "evt_old" })
+
+      setNow(100 * DAY)
+      const summary = yield* s.sweepOnce()
+      expect(summary.deletedEventV2Sequences).toBe(1)
+
+      // Both the event_sequence header and the event row (cascaded) must be gone.
+      const seqs = yield* db.select().from(EventSequenceTable).all().pipe(Effect.orDie)
+      expect(seqs.find((r) => r.aggregate_id === "ses_old")).toBeUndefined()
+      const evts = yield* db.select().from(EventTable).all().pipe(Effect.orDie)
+      expect(evts.find((r) => r.id === "evt_old")).toBeUndefined()
+    }),
+  )
+
+  it.effect("§EventV2-retention: spares event_sequence rows for recently-archived sessions", () =>
+    Effect.gen(function* () {
+      const { db } = yield* Database.Service
+      const b = yield* DeepAgentEventBus.Service
+      const c = yield* WorkspaceConfig.Service
+      const s = yield* RetentionSweeper.Service
+      yield* c.set("wrk_1", { retentionDays: 30 })
+      yield* publishAt(b, 100 * DAY)
+
+      // Archived just now — not yet past retentionDays.
+      yield* insertArchivedSession({ sessionID: "ses_new", workspaceID: "wrk_1", timeArchived: 100 * DAY })
+      yield* insertEventV2({ sessionID: "ses_new", eventID: "evt_new" })
+
+      setNow(100 * DAY)
+      const summary = yield* s.sweepOnce()
+      expect(summary.deletedEventV2Sequences).toBe(0)
+
+      const seqs = yield* db.select().from(EventSequenceTable).all().pipe(Effect.orDie)
+      expect(seqs.find((r) => r.aggregate_id === "ses_new")).toBeDefined()
+    }),
+  )
+
+  it.effect("§EventV2-retention: spares event_sequence rows for non-archived sessions", () =>
+    Effect.gen(function* () {
+      const { db } = yield* Database.Service
+      const b = yield* DeepAgentEventBus.Service
+      const c = yield* WorkspaceConfig.Service
+      const s = yield* RetentionSweeper.Service
+      yield* c.set("wrk_1", { retentionDays: 30 })
+      yield* publishAt(b, 1_000)
+
+      // Insert with a placeholder time_archived, then clear it to NULL → active session.
+      yield* insertArchivedSession({ sessionID: "ses_active", workspaceID: "wrk_1", timeArchived: 0 })
+      yield* db
+        .run(`UPDATE session SET time_archived = NULL WHERE id = 'ses_active'`)
+        .pipe(Effect.orDie)
+      yield* insertEventV2({ sessionID: "ses_active", eventID: "evt_active" })
+
+      setNow(100 * DAY)
+      const summary = yield* s.sweepOnce()
+      expect(summary.deletedEventV2Sequences).toBe(0)
+
+      const seqs = yield* db.select().from(EventSequenceTable).all().pipe(Effect.orDie)
+      expect(seqs.find((r) => r.aggregate_id === "ses_active")).toBeDefined()
+    }),
+  )
 })

From e6bcf6ab3cc5c83f3a512bbc6f2722c3a1739fd7 Mon Sep 17 00:00:00 2001
From: deepagent-ai <jamessmithm539@gmail.com>
Date: Tue, 21 Jul 2026 10:05:24 +0800
Subject: [PATCH 2/5] =?UTF-8?q?fix(provider):=20=E4=BF=AE=E5=A4=8D=20OpenA?=
 =?UTF-8?q?I/Anthropic=20=E6=A8=A1=E5=9E=8B=E6=8E=A8=E7=90=86=E5=BC=BA?=
 =?UTF-8?q?=E5=BA=A6=E7=BC=BA=E5=A4=B1=20xhigh=20=E7=9A=84=E4=B8=A4?=
 =?UTF-8?q?=E4=B8=AA=20bug?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

**问题**
1. OpenAI gpt-5.6-sol 等新模型在走 @ai-sdk/openai-compatible 路径时只显示
   low/medium/high（无 xhigh），而 Codex 等 @ai-sdk/openai 路径可以正确显示。
2. Anthropic Fable 5 等新模型不在 anthropicAdaptiveEfforts() 的识别列表里，
   导致退回旧的 budgetTokens 模式，只有 high/max 两档。

**根因**
- Bug #1 (@ai-sdk/openai-compatible)：variants() 里该 case 直接硬写
  WIDELY_SUPPORTED_EFFORTS，从不调 openaiCompatibleReasoningEfforts()，
  所以无论 api.id 是多新的 gpt-5.x，都只给 low/medium/high。
  @ai-sdk/openai（直连）和 @ai-sdk/gateway 路径调用了正确的函数，所以表现一致。
- Bug #2 (Fable 5)：anthropicAdaptiveEfforts()/anthropicOpus47OrLater() 只匹配
  "opus-X.Y" 和 "sonnet-4.6" 模式，"fable-5" 不含任何上述关键词 → 返回 null
  → 走旧 { high: {budgetTokens:16000}, max: {budgetTokens:31999} }。

**修复**
- Bug #1：@ai-sdk/openai-compatible case 里对 GPT-5 family (GPT5_FAMILY_RE) 的模型
  调用 openaiCompatibleReasoningEfforts()，非 GPT-5 模型维持原有 low/medium/high。
- Bug #2：新增 anthropicFable5OrLater() 函数（匹配 "fable-5/fable.5" 等格式，
  版本号≥5 即生效），更新 anthropicAdaptiveEfforts() 和 adaptiveOpus 同时识别 Fable 5+。
  Fable 5 获得 ["low","medium","high","xhigh","max"] 和 display:"summarized"（与 Opus 4.7+ 一致）。

**测试**
- 新增：openai-compatible gpt-5.6-sol 返回 xhigh / 非 gpt-5 仍只有 low/medium/high
- 新增：fable-5 / claude-fable-5-20260720 返回 xhigh 含 display:summarized
- 260/261 通过（唯一失败是预存在的 azure 测试，与本次改动无关）

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../deepagent-code/src/provider/transform.ts  | 27 +++++++++++--
 .../test/provider/transform.test.ts           | 39 +++++++++++++++++++
 2 files changed, 62 insertions(+), 4 deletions(-)

diff --git a/packages/deepagent-code/src/provider/transform.ts b/packages/deepagent-code/src/provider/transform.ts
index d2a0f1aa..2b44e055 100644
--- a/packages/deepagent-code/src/provider/transform.ts
+++ b/packages/deepagent-code/src/provider/transform.ts
@@ -591,8 +591,16 @@ function anthropicOpus47OrLater(apiId: string) {
   return major > 4 || (major === 4 && minor >= 7)
 }
 
+// Matches "fable-5", "claude-fable-5", "claude-fable-5-20260720", etc.
+// Fable 5 supports the full adaptive thinking effort set (same as Opus 4.7+).
+function anthropicFable5OrLater(apiId: string) {
+  const m = /fable[._-]?(\d+)/i.exec(apiId)
+  return m !== null && Number(m[1]) >= 5
+}
+
 function anthropicAdaptiveEfforts(apiId: string): string[] | null {
-  if (anthropicOpus47OrLater(apiId)) {
+  // Opus 4.7+ and Fable 5+ support the full adaptive effort set including xhigh.
+  if (anthropicOpus47OrLater(apiId) || anthropicFable5OrLater(apiId)) {
     return ["low", "medium", "high", "xhigh", "max"]
   }
   if (
@@ -648,7 +656,9 @@ export function variants(model: Provider.Model): Record<string, Record<string, a
   if (!model.capabilities.reasoning) return {}
 
   const id = model.id.toLowerCase()
-  const adaptiveOpus = anthropicOpus47OrLater(model.api.id)
+  // `adaptiveOpus` gates the `display: "summarized"` inject. Opus 4.7+ flipped the API default
+  // for thinking-display to "omitted"; Fable 5+ follows the same convention.
+  const adaptiveOpus = anthropicOpus47OrLater(model.api.id) || anthropicFable5OrLater(model.api.id)
   const adaptiveEfforts = anthropicAdaptiveEfforts(model.api.id)
   if (glm52(model)) {
     if (model.api.npm === "@openrouter/ai-sdk-provider") {
@@ -827,12 +837,21 @@ export function variants(model: Provider.Model): Record<string, Record<string, a
     // https://v5.ai-sdk.dev/providers/ai-sdk-providers/deepinfra
     case "venice-ai-sdk-provider":
     // https://docs.venice.ai/overview/guides/reasoning-models#reasoning-effort
-    case "@ai-sdk/openai-compatible":
+    case "@ai-sdk/openai-compatible": {
+      // For GPT-5.x versioned models routed through an openai-compatible endpoint, respect their
+      // extended effort tiers (xhigh from v5.2+) — same resolution logic as @ai-sdk/gateway.
+      // All other models on this adapter fall back to the base low/medium/high set.
+      const apiId = model.api.id.toLowerCase()
+      if (GPT5_FAMILY_RE.test(apiId)) {
+        const openaiCompatEfforts = openaiCompatibleReasoningEfforts(apiId)
+        return Object.fromEntries(openaiCompatEfforts.map((effort) => [effort, { reasoningEffort: effort }]))
+      }
       const efforts = [...WIDELY_SUPPORTED_EFFORTS]
-      if (model.api.id.toLowerCase().includes("deepseek-v4")) {
+      if (apiId.includes("deepseek-v4")) {
         efforts.push("max")
       }
       return Object.fromEntries(efforts.map((effort) => [effort, { reasoningEffort: effort }]))
+    }
 
     case "@ai-sdk/azure":
       // https://v5.ai-sdk.dev/providers/ai-sdk-providers/azure
diff --git a/packages/deepagent-code/test/provider/transform.test.ts b/packages/deepagent-code/test/provider/transform.test.ts
index 98eaf240..b09ce0bd 100644
--- a/packages/deepagent-code/test/provider/transform.test.ts
+++ b/packages/deepagent-code/test/provider/transform.test.ts
@@ -2528,6 +2528,37 @@ describe("ProviderTransform.variants", () => {
     })
   })
 
+  // Bug fix: gpt-5.x models on @ai-sdk/openai-compatible endpoints now get the extended
+  // effort set (xhigh from gpt-5.2+). Previously the adapter always returned low/medium/high.
+  test("openai-compatible gpt-5.6-sol returns xhigh reasoning effort", () => {
+    const model = createMockModel({
+      id: "cortecs/gpt-5.6-sol",
+      providerID: "cortecs",
+      api: {
+        id: "gpt-5.6-sol",
+        url: "https://api.cortecs.ai/v1",
+        npm: "@ai-sdk/openai-compatible",
+      },
+    })
+    const result = ProviderTransform.variants(model)
+    expect(Object.keys(result)).toEqual(["none", "low", "medium", "high", "xhigh"])
+    expect(result.xhigh).toEqual({ reasoningEffort: "xhigh" })
+  })
+
+  test("openai-compatible non-gpt5 model still gets only low/medium/high", () => {
+    const model = createMockModel({
+      id: "third-party/some-model",
+      providerID: "third-party",
+      api: {
+        id: "some-model",
+        url: "https://api.third-party.ai/v1",
+        npm: "@ai-sdk/openai-compatible",
+      },
+    })
+    const result = ProviderTransform.variants(model)
+    expect(Object.keys(result)).toEqual(["low", "medium", "high"])
+  })
+
   test("mistral models with reasoning support return variants", () => {
     const model = createMockModel({
       id: "mistral/mistral-small-latest",
@@ -3388,6 +3419,14 @@ describe("ProviderTransform.variants", () => {
         efforts: ["low", "medium", "high", "xhigh", "max"],
         expectedHigh: { thinking: { type: "adaptive", display: "summarized" }, effort: "high" },
       },
+      {
+        // Bug fix: Fable 5 is a distinct Claude model family that supports the full adaptive
+        // effort set (including xhigh) with display: "summarized" (like Opus 4.7+).
+        name: "fable 5",
+        apiIds: ["claude-fable-5", "claude-fable-5-20260720"],
+        efforts: ["low", "medium", "high", "xhigh", "max"],
+        expectedHigh: { thinking: { type: "adaptive", display: "summarized" }, effort: "high" },
+      },
     ]) {
       for (const apiId of testCase.apiIds) {
         test(`${testCase.name} ${apiId} returns supported reasoning efforts`, () => {

From 9989c342a47387ad5ad664c1438b85b679c1204e Mon Sep 17 00:00:00 2001
From: deepagent-ai <jamessmithm539@gmail.com>
Date: Wed, 22 Jul 2026 20:41:45 +0800
Subject: [PATCH 3/5] Fix/provider reasoning intensity xhigh (#83)

### Issue for this PR

Closes #

### Type of change

- [ ] Bug fix
- [ ] New feature
- [ ] Refactor / code improvement
- [ ] Documentation

### What does this PR do?

Please provide a description of the issue, the changes you made to fix
it, and why they work. It is expected that you understand why your
changes work and if you do not understand why at least say as much so a
maintainer knows how much to value the PR.

**If you paste a large clearly AI generated description here your PR may
be IGNORED or CLOSED!**

### How did you verify your code works?

### Screenshots / recordings

_If this is a UI change, please include a screenshot or recording._

### Checklist

- [ ] I have tested my changes locally
- [ ] I have not included unrelated changes in this PR

_If you do not follow this template your PR will be automatically
rejected._

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
---
 packages/app/package.json                     |   2 +-
 packages/app/src/app.tsx                      |  21 +-
 .../deepagent/oversight-dashboard.tsx         |  46 ++++-
 .../src/components/deepagent/oversight.api.ts |   5 +-
 .../src/components/session/session-header.tsx |  23 ++-
 packages/app/src/context/layout.tsx           |  23 ++-
 packages/app/src/context/terminal.test.ts     |  28 +++
 packages/app/src/context/terminal.tsx         |  70 +++++--
 packages/app/src/i18n/en.ts                   |   3 +-
 packages/app/src/i18n/zh.ts                   |   3 +-
 packages/app/src/pages/layout.tsx             |   4 +-
 packages/app/src/pages/session.tsx            |  60 +++---
 .../composer/session-composer-region.tsx      |   2 +
 .../composer/session-followup-dock.tsx        |  10 +
 .../pages/session/message-timeline.data.ts    |   4 +-
 .../src/pages/session/session-side-panel.tsx  |  94 ++++-----
 .../pages/session/side-panel-subagents.tsx    | 147 +++++++++++---
 .../src/pages/session/side-panel-terminal.tsx | 141 ++++++++------
 .../app/src/pages/session/terminal-panel.tsx  |  65 +++----
 .../app/src/pages/session/terminal-view.tsx   |  38 ++--
 .../pages/session/use-session-commands.tsx    |  60 +++---
 packages/core/src/database/database.ts        |   3 +-
 .../core/src/deepagent/deepagent-event-bus.ts |  10 +-
 packages/deepagent-code/src/cli/cmd/mcp.ts    |  16 +-
 .../src/panel/panel-convene-consumer.ts       |   6 +-
 .../deepagent-code/src/provider/transform.ts  |  20 +-
 .../instance/httpapi/handlers/session.ts      |   7 +-
 .../src/session/event-dispatcher.ts           |   1 +
 .../src/session/goal-tick-consumer.ts         |   6 +-
 packages/deepagent-code/src/session/prompt.ts | 105 +++++++++-
 .../src/session/supervisor-notifier.ts        |   6 +-
 .../src/session/v4-event-runtime.ts           |  28 ++-
 packages/deepagent-code/src/tool/registry.ts  |   4 +
 packages/deepagent-code/src/tool/task.ts      |  78 ++++++--
 packages/deepagent-code/src/tool/task_read.ts | 182 ++++++++++++++++++
 .../deepagent-code/src/tool/task_status.ts    |  99 ++++++++--
 .../src/wiki/event-driven-archiver.ts         |   6 +-
 .../deepagent-code/test/cli/mcp-add.test.ts   |  17 +-
 .../test/provider/transform.test.ts           |  29 ++-
 .../test/session/structured-output.test.ts    |  70 +++++++
 .../test/tool/task-status.test.ts             |  79 +++-----
 .../test/tool/task-takeover.test.ts           |  10 +-
 packages/desktop/package.json                 |   2 +-
 packages/desktop/src/main/index.ts            |   8 +-
 packages/desktop/src/main/sidecar.ts          |  10 +-
 45 files changed, 1209 insertions(+), 442 deletions(-)
 create mode 100644 packages/deepagent-code/src/tool/task_read.ts

diff --git a/packages/app/package.json b/packages/app/package.json
index 625b3083..3d4e8646 100644
--- a/packages/app/package.json
+++ b/packages/app/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepagent-code/app",
-  "version": "1.4.2",
+  "version": "1.4.3",
   "description": "",
   "type": "module",
   "exports": {
diff --git a/packages/app/src/app.tsx b/packages/app/src/app.tsx
index 1568b3df..7acbad26 100644
--- a/packages/app/src/app.tsx
+++ b/packages/app/src/app.tsx
@@ -9,7 +9,7 @@ import { Font } from "@deepagent-code/ui/font"
 import { Splash } from "@deepagent-code/ui/logo"
 import { ThemeProvider } from "@deepagent-code/ui/theme/context"
 import { MetaProvider } from "@solidjs/meta"
-import { type BaseRouterProps, Navigate, Route, Router } from "@solidjs/router"
+import { type BaseRouterProps, Navigate, Route, Router, useLocation, useNavigate } from "@solidjs/router"
 import { QueryClient, QueryClientProvider } from "@tanstack/solid-query"
 import { Effect } from "effect"
 import {
@@ -45,7 +45,7 @@ import { PromptProvider } from "@/context/prompt"
 import { ServerConnection, ServerProvider, serverName, useServer } from "@/context/server"
 import { SettingsProvider } from "@/context/settings"
 import { TerminalProvider } from "@/context/terminal"
-import { TabsProvider } from "@/context/tabs"
+import { TabsProvider, useTabs } from "@/context/tabs"
 import { WslServersProvider } from "@/wsl/context"
 import DirectoryLayout from "@/pages/directory-layout"
 import Layout from "@/pages/layout"
@@ -143,6 +143,23 @@ function SessionProviders(props: ParentProps) {
 }
 
 function RouterRoot(props: ParentProps<{ appChildren?: JSX.Element }>) {
+  const tabs = useTabs()
+  const navigate = useNavigate()
+  const location = useLocation()
+
+  // On startup: as soon as persisted tabs are loaded (local disk, no HTTP calls),
+  // navigate to the last visited project's session list. This matches opencode's approach —
+  // use local/cached data to drive the first frame, let the server data fill in asynchronously.
+  // We navigate to /:dir/session (no specific session ID) so autoselecting can handle
+  // the final session selection independently without conflicting navigation.
+  createEffect(() => {
+    if (!tabs.ready()) return
+    if (location.pathname !== "/") return
+    const first = tabs.store[0]
+    if (!first) return
+    navigate(`/${first.dirBase64}/session`, { replace: true })
+  })
+
   return (
     <AppShellProviders>
       {/*<Suspense fallback={<Loading />}>*/}
diff --git a/packages/app/src/components/deepagent/oversight-dashboard.tsx b/packages/app/src/components/deepagent/oversight-dashboard.tsx
index 58ec0cd5..09f72cd3 100644
--- a/packages/app/src/components/deepagent/oversight-dashboard.tsx
+++ b/packages/app/src/components/deepagent/oversight-dashboard.tsx
@@ -55,7 +55,16 @@ function MetricCard(props: { label: string; value: string; tone?: "ok" | "warn"
   )
 }
 
-export const OversightDashboard: Component = () => {
+// Phase 2: OversightDashboard now accepts a selected subagent session ID so takeover/rollback
+// automatically target the chosen session, and trace nodes can reverse-select a subagent.
+export type OversightDashboardProps = {
+  /** When provided, takeover and rollback default to this session ID. */
+  selectedSessionID?: string
+  /** Called when a trace node with a sessionID is clicked so the caller can select that subagent. */
+  onSessionSelect?: (sessionID: string) => void
+}
+
+export const OversightDashboard: Component<OversightDashboardProps> = (props) => {
   const sdk = useSDK()
   const language = useLanguage()
   const client = () => sdk.client as unknown as OversightClient
@@ -118,7 +127,9 @@ export const OversightDashboard: Component = () => {
     if (!reason) return
     setTakeoverBusy(true)
     setTakeoverNote(null)
-    const result = await recordHumanTakeover(client(), { reason })
+    // Phase 2: automatically pass the selected session ID when present.
+    const sessionID = props.selectedSessionID
+    const result = await recordHumanTakeover(client(), { reason, ...(sessionID ? { sessionID } : {}) })
     setTakeoverBusy(false)
     if (result.ok) {
       setTakeoverReason("")
@@ -133,13 +144,17 @@ export const OversightDashboard: Component = () => {
   }
 
   // ── §D2 rollback (P4.4) ─────────────────────────────────────────────────────────
-  const [rollbackSession, setRollbackSession] = createSignal("")
+  // Phase 2: rollback input is pre-seeded with the selected session ID. Users may override it.
   const [rollbackReason, setRollbackReason] = createSignal("")
   const [rollbackBusy, setRollbackBusy] = createSignal(false)
   const [rollbackNote, setRollbackNote] = createSignal<string | null>(null)
 
+  // The effective session ID for rollback: the input field overrides; falls back to selectedSessionID.
+  const [rollbackSessionOverride, setRollbackSessionOverride] = createSignal("")
+  const effectiveRollbackSession = () => rollbackSessionOverride() || props.selectedSessionID || ""
+
   const submitRollback = async () => {
-    const sessionID = rollbackSession().trim()
+    const sessionID = effectiveRollbackSession().trim()
     if (!sessionID) return
     const reason = rollbackReason().trim()
     setRollbackBusy(true)
@@ -147,7 +162,7 @@ export const OversightDashboard: Component = () => {
     const result = await recordRollback(client(), { sessionID, ...(reason ? { reason } : {}) })
     setRollbackBusy(false)
     if (result.ok) {
-      setRollbackSession("")
+      setRollbackSessionOverride("")
       setRollbackReason("")
       setRollbackNote(
         result.record?.outcome === "noop"
@@ -328,6 +343,17 @@ export const OversightDashboard: Component = () => {
                             </div>
                           </Show>
                           <div class="text-11-regular text-text-weaker">{fmtTime(node.createdAt)}</div>
+                          {/* Phase 2: if this node is tied to a specific subagent session, offer
+                              a reverse-select link so the user can jump to that subagent row. */}
+                          <Show when={node.sessionID && props.onSessionSelect}>
+                            <button
+                              type="button"
+                              class="mt-0.5 text-11-regular text-text-link hover:underline"
+                              onClick={() => props.onSessionSelect!(node.sessionID!)}
+                            >
+                              {language.t("oversight.trace.selectAgent")}
+                            </button>
+                          </Show>
                         </div>
                       </div>
                     )}
@@ -372,11 +398,13 @@ export const OversightDashboard: Component = () => {
         <section>
           <h3 class="mb-1 text-13-medium text-text-strong">{language.t("oversight.rollback.title")}</h3>
           <p class="mb-2 text-11-regular text-text-weak">{language.t("oversight.rollback.description")}</p>
+          {/* Phase 2: when a subagent is selected the placeholder is replaced by the session ID.
+              Typing in this field overrides the pre-selected session. */}
           <input
             class="w-full rounded-md border border-border-weak-base bg-surface-base px-2 py-1.5 text-12-regular text-text-strong outline-none focus:ring-2 focus:ring-accent-base font-mono"
-            placeholder={language.t("oversight.rollback.sessionPlaceholder")}
-            value={rollbackSession()}
-            onInput={(e) => setRollbackSession(e.currentTarget.value)}
+            placeholder={props.selectedSessionID || language.t("oversight.rollback.sessionPlaceholder")}
+            value={rollbackSessionOverride()}
+            onInput={(e) => setRollbackSessionOverride(e.currentTarget.value)}
           />
           <textarea
             class="mt-2 w-full rounded-md border border-border-weak-base bg-surface-base px-2 py-1.5 text-12-regular text-text-strong outline-none resize-none focus:ring-2 focus:ring-accent-base"
@@ -391,7 +419,7 @@ export const OversightDashboard: Component = () => {
               size="small"
               icon="reset"
               onClick={submitRollback}
-              disabled={rollbackBusy() || !rollbackSession().trim()}
+              disabled={rollbackBusy() || !effectiveRollbackSession().trim()}
             >
               <Show when={rollbackBusy()}>
                 <Spinner />
diff --git a/packages/app/src/components/deepagent/oversight.api.ts b/packages/app/src/components/deepagent/oversight.api.ts
index 57178c85..8178f3a4 100644
--- a/packages/app/src/components/deepagent/oversight.api.ts
+++ b/packages/app/src/components/deepagent/oversight.api.ts
@@ -54,6 +54,9 @@ export type OversightTraceNode = {
   source: string
   causationID?: string
   createdAt: number
+  // Phase 2: trace nodes may carry the session that emitted them so the UI can reverse-select
+  // the subagent row when the user clicks a trace entry.
+  sessionID?: string
 }
 export type OversightTrace = { nodes: OversightTraceNode[] }
 
@@ -148,7 +151,7 @@ export type HumanTakeoverRecord = {
  */
 export const recordHumanTakeover = async (
   client: OversightClient,
-  input: { reason: string; scope?: string },
+  input: { reason: string; scope?: string; sessionID?: string },
 ): Promise<{ ok: true; record?: HumanTakeoverRecord } | { ok: false; unsupported: boolean; error: string }> => {
   try {
     const response = await client.client.request<HumanTakeoverRecord>({
diff --git a/packages/app/src/components/session/session-header.tsx b/packages/app/src/components/session/session-header.tsx
index 6a66fd22..810ddc87 100644
--- a/packages/app/src/components/session/session-header.tsx
+++ b/packages/app/src/components/session/session-header.tsx
@@ -18,7 +18,7 @@ import { DOCK_PANEL_IDS, useLayout } from "@/context/layout"
 import { usePlatform } from "@/context/platform"
 import { useServer } from "@/context/server"
 import { useSync } from "@/context/sync"
-import { useTerminal } from "@/context/terminal"
+import { useTerminalHosts } from "@/context/terminal"
 import { focusTerminalById } from "@/pages/session/helpers"
 import { useSessionLayout } from "@/pages/session/session-layout"
 import { PANEL_VIEW_META } from "@/pages/session/panel-view-registry"
@@ -144,7 +144,7 @@ export function SessionHeader() {
   const platform = usePlatform()
   const language = useLanguage()
   const sync = useSync()
-  const terminal = useTerminal()
+  const terminalHosts = useTerminalHosts()
   const { params, view } = useSessionLayout()
 
   const projectDirectory = createMemo(() => decode64(params.dir) ?? "")
@@ -208,19 +208,18 @@ export function SessionHeader() {
     ]
   })
 
-  const terminalOpen = createMemo(() => {
-    const panel = view().panel
-    return panel.location("terminal") === "bottom"
-      ? panel.bottom.opened() && panel.bottom.activeView() === "terminal"
-      : view().rightPanel.mode() === "terminal"
-  })
+  // Phase 3: terminal toggle button in the header controls the **bottom** terminal only.
+  const terminalOpen = createMemo(() =>
+    view().panel.bottom.opened() && view().panel.bottom.activeView() === "terminal",
+  )
 
   const toggleTerminal = () => {
     view().panel.toggle("terminal")
-    const panel = view().panel
-    if (panel.location("terminal") === "side" && view().rightPanel.mode() !== "terminal") return
-    const id = terminal.active()
-    if (id) focusTerminalById(id)
+    // Focus the bottom terminal's active pane after opening.
+    if (terminalOpen()) {
+      const id = terminalHosts.bottom.active()
+      if (id) focusTerminalById(id)
+    }
   }
 
   const bottomPanelOpen = createMemo(() => view().panel.bottom.opened())
diff --git a/packages/app/src/context/layout.tsx b/packages/app/src/context/layout.tsx
index cbc04598..fca1b7b4 100644
--- a/packages/app/src/context/layout.tsx
+++ b/packages/app/src/context/layout.tsx
@@ -105,6 +105,8 @@ type SessionView = {
   // U3/U4/U7: added "worktree" (isolated worktree diff/merge), "subagents" (child-session list),
   // "browser" (isolated WebContentsView).
   // T3.2: the "menu" mode is gone — an always-on icon rail replaced the full-panel menu list.
+  // Phase 2: "oversight" removed as standalone panel; kept in union only for backward-compat
+  // migration — any stored "oversight" is silently mapped to "subagents" at read time.
   rightPanelMode?:
     | "review"
     | "files"
@@ -326,7 +328,7 @@ export const { use: useLayout, provider: LayoutProvider } = createSimpleContext(
       { ...target, migrate },
       createStore({
         sidebar: {
-          opened: false,
+          opened: true,
           width: DEFAULT_SIDEBAR_WIDTH,
           workspaces: {} as Record<string, boolean>,
           workspacesDefault: false,
@@ -731,12 +733,16 @@ export const { use: useLayout, provider: LayoutProvider } = createSimpleContext(
         },
       },
       dock: {
-        // Deprecated compatibility metadata. New UI must use view(session).panel;
-        // only locations and the shared Bottom Panel dimension remain global.
+        // Phase 3: terminal is now side-native in the right panel (independent host).
+        // dock.location("terminal") is forced to "bottom" to avoid stale stored "side"
+        // values making the bottom terminal unreachable. Move operations for terminal
+        // are intentionally no-ops; only debug-console and problems remain movable.
         location(id: DockPanelID): DockLocation {
+          if (id === "terminal") return "bottom"
           return store.dock?.location?.[id] ?? DOCK_DEFAULT_LOCATION[id]
         },
         setLocation(id: DockPanelID, location: DockLocation) {
+          if (id === "terminal") return // terminal location is now fixed
           if (!store.dock) {
             setStore("dock", { location: { [id]: location } as Record<DockPanelID, DockLocation> })
             return
@@ -744,6 +750,7 @@ export const { use: useLayout, provider: LayoutProvider } = createSimpleContext(
           setStore("dock", "location", id, location)
         },
         move(id: DockPanelID) {
+          if (id === "terminal") return // terminal is no longer movable
           const current = store.dock?.location?.[id] ?? DOCK_DEFAULT_LOCATION[id]
           const next: DockLocation = current === "bottom" ? "side" : "bottom"
           if (!store.dock) {
@@ -753,7 +760,7 @@ export const { use: useLayout, provider: LayoutProvider } = createSimpleContext(
           setStore("dock", "location", id, next)
         },
         bottomCount: createMemo(
-          () => DOCK_PANEL_IDS.filter((id) => (store.dock?.location?.[id] ?? DOCK_DEFAULT_LOCATION[id]) === "bottom").length,
+          () => DOCK_PANEL_IDS.filter((id) => (id === "terminal" ? true : (store.dock?.location?.[id] ?? DOCK_DEFAULT_LOCATION[id]) === "bottom")).length,
         ),
       },
       review: {
@@ -905,7 +912,13 @@ export const { use: useLayout, provider: LayoutProvider } = createSimpleContext(
         const key = createSessionKeyReader(sessionKey, ensureKey)
         const s = createMemo(() => store.sessionView[key()] ?? { scroll: {} })
         const reviewPanelOpened = createMemo(() => store.review?.panelOpened ?? true)
-        const rightPanelMode = createMemo(() => store.sessionView[key()]?.rightPanelMode)
+        const rightPanelMode = createMemo(() => {
+          const mode = store.sessionView[key()]?.rightPanelMode
+          // Phase 2 backward-compat: "oversight" was merged into "subagents". Any session that
+          // persisted "oversight" should silently open the unified subagents panel instead.
+          if (mode === "oversight") return "subagents" as SessionRightPanelMode
+          return mode
+        })
         const bottomPanel = createMemo(() => {
           const current = store.sessionView[key()]
           // One-way compatibility migration from the pre-panel global terminal flag.
diff --git a/packages/app/src/context/terminal.test.ts b/packages/app/src/context/terminal.test.ts
index d9739865..dbaabd9f 100644
--- a/packages/app/src/context/terminal.test.ts
+++ b/packages/app/src/context/terminal.test.ts
@@ -339,6 +339,34 @@ describe("runtime terminal controller", () => {
     }
   })
 
+  test("collapses a split to its surviving pane when closing that pane's final terminal", async () => {
+    let sequence = 0
+    const harness = terminalHarness(async () => {
+      sequence += 1
+      return { data: { id: `pty-${sequence}`, title: `Terminal ${sequence}` } }
+    })
+    try {
+      await harness.session.new()
+      harness.session.setPaneBounds(harness.session.focusedPaneId(), { width: 1_000, height: 400 })
+      expect(await harness.session.split("horizontal")).toBeTrue()
+
+      const [first, second] = harness.session.all()
+      expect(first).toBeDefined()
+      expect(second).toBeDefined()
+      await harness.session.close(second!.id)
+
+      const root = harness.session.root()
+      expect(root.kind).toBe("leaf")
+      if (root.kind !== "leaf") throw new Error("expected split to collapse to a leaf")
+      expect(root.ptys).toEqual([first!.id])
+      expect(root.activeId).toBe(first!.id)
+      expect(harness.session.focusedPaneId()).toBe(root.id)
+      expect(harness.session.closeRequest()).toBe(0)
+    } finally {
+      harness.dispose()
+    }
+  })
+
   test("requests panel close only when the user closes the final tab", async () => {
     const harness = terminalHarness(async () => ({ data: { id: "pty-server-1", title: "Terminal 1" } }))
     try {
diff --git a/packages/app/src/context/terminal.tsx b/packages/app/src/context/terminal.tsx
index ee2f91d6..65c76500 100644
--- a/packages/app/src/context/terminal.tsx
+++ b/packages/app/src/context/terminal.tsx
@@ -1,6 +1,6 @@
 import { createStore } from "solid-js/store"
 import { createSimpleContext } from "@deepagent-code/ui/context"
-import { batch, createMemo, createSignal, onCleanup, onMount } from "solid-js"
+import { batch, createContext, createMemo, createSignal, onCleanup, onMount, useContext, type JSX, type ParentProps } from "solid-js"
 import { useSDK } from "./sdk"
 import { usePlatform, type Platform } from "./platform"
 import { useServer } from "./server"
@@ -727,8 +727,11 @@ function createWorkspaceTerminalSession(
 
 /** @internal */ export const TerminalTesting = { createWorkspaceTerminalSession }
 
-export const { use: useTerminal, provider: TerminalProvider } = createSimpleContext({
-  name: "Terminal",
+export type TerminalHostID = "bottom" | "side"
+
+// Dual-host provider — creates independent bottom and side sessions sharing one PTY service.
+const { use: useTerminalDual, provider: TerminalProvider } = createSimpleContext({
+  name: "TerminalDual",
   gate: false,
   init: () => {
     const sdk = useSDK()
@@ -737,9 +740,10 @@ export const { use: useTerminal, provider: TerminalProvider } = createSimpleCont
     const scope = server.scope()
     let runtimeId: string | undefined
     let runtimeRequest: Promise<void> | undefined
-    let terminal: TerminalSession | undefined
+    let bottomSession: TerminalSession | undefined
+    let sideSession: TerminalSession | undefined
 
-    const ensureRuntime = () => {
+    const ensureRuntime = (): Promise<void> => {
       if (runtimeRequest) return runtimeRequest
       runtimeRequest = sdk.client.global
         .health({ cache: "no-store" })
@@ -752,7 +756,8 @@ export const { use: useTerminal, provider: TerminalProvider } = createSimpleCont
           if (runtimeId === next) return
           console.info("[terminal] server runtime changed", { previousRuntimeId: runtimeId, runtimeId: next })
           runtimeId = next
-          terminal?.resetRuntime()
+          bottomSession?.resetRuntime()
+          sideSession?.resetRuntime()
         })
         .catch((error) => {
           if (import.meta.env.DEV) console.debug("[terminal] runtime check failed", error)
@@ -760,26 +765,63 @@ export const { use: useTerminal, provider: TerminalProvider } = createSimpleCont
         .finally(() => {
           runtimeRequest = undefined
         })
-      return runtimeRequest
+      return runtimeRequest as Promise<void>
     }
 
-    terminal = createWorkspaceTerminalSession(sdk, { id: () => runtimeId, ensure: ensureRuntime })
-    const registered = { dir: sdk.directory, scope, value: terminal }
-    sessions.add(registered)
+    const runtime = { id: () => runtimeId, ensure: ensureRuntime }
+    bottomSession = createWorkspaceTerminalSession(sdk, runtime)
+    sideSession = createWorkspaceTerminalSession(sdk, runtime)
+
+    const bottomReg = { dir: sdk.directory, scope, value: bottomSession }
+    const sideReg = { dir: sdk.directory, scope, value: sideSession }
+    sessions.add(bottomReg)
+    sessions.add(sideReg)
     removeTerminalPersistence(sdk.directory, undefined, platform, scope)
 
     onMount(() => {
       void ensureRuntime()
       const timer = setInterval(() => {
-        if (terminal?.all().length) void ensureRuntime()
+        if (bottomSession?.all().length || sideSession?.all().length) void ensureRuntime()
       }, RUNTIME_POLL_MS)
       onCleanup(() => clearInterval(timer))
     })
     onCleanup(() => {
-      sessions.delete(registered)
-      terminal?.clear()
+      sessions.delete(bottomReg)
+      sessions.delete(sideReg)
+      bottomSession?.clear()
+      sideSession?.clear()
     })
 
-    return terminal
+    return { bottom: bottomSession, side: sideSession }
   },
 })
+
+// Re-export TerminalProvider for app.tsx
+export { TerminalProvider }
+
+// useTerminalHosts — returns { bottom, side } for callers that need to address a specific host.
+export function useTerminalHosts() {
+  return useTerminalDual()
+}
+
+// Per-render-tree host context — populated by BottomTerminalProvider / SideTerminalProvider.
+// All components inside terminal-view.tsx (TerminalPanes, TerminalActions, …) consume this.
+const TerminalHostContext = createContext<TerminalSession | undefined>(undefined)
+
+export function useTerminal(): TerminalSession {
+  const ctx = useContext(TerminalHostContext)
+  if (!ctx) throw new Error("useTerminal must be called inside BottomTerminalProvider or SideTerminalProvider")
+  return ctx
+}
+
+/** Wrap the bottom-dock rendering subtree so all terminal-view components target the bottom session. */
+export function BottomTerminalProvider(props: ParentProps) {
+  const hosts = useTerminalDual()
+  return <TerminalHostContext.Provider value={hosts.bottom}>{props.children}</TerminalHostContext.Provider>
+}
+
+/** Wrap the side-panel rendering subtree so all terminal-view components target the side session. */
+export function SideTerminalProvider(props: ParentProps) {
+  const hosts = useTerminalDual()
+  return <TerminalHostContext.Provider value={hosts.side}>{props.children}</TerminalHostContext.Provider>
+}
diff --git a/packages/app/src/i18n/en.ts b/packages/app/src/i18n/en.ts
index 430fd0dd..fafc77d1 100644
--- a/packages/app/src/i18n/en.ts
+++ b/packages/app/src/i18n/en.ts
@@ -921,8 +921,9 @@ export const dict = {
   "session.question.progress": "{{current}} of {{total}} questions",
   "session.followupDock.summary.one": "{{count}} queued message",
   "session.followupDock.summary.other": "{{count}} queued messages",
-  "session.followupDock.sendNow": "Send now",
+  "session.followupDock.sendNow": "Send steer",
   "session.followupDock.edit": "Edit",
+  "session.followupDock.delete": "Discard",
   "session.followupDock.collapse": "Collapse queued messages",
   "session.followupDock.expand": "Expand queued messages",
   "session.revertDock.summary.one": "{{count}} rolled back message",
diff --git a/packages/app/src/i18n/zh.ts b/packages/app/src/i18n/zh.ts
index b1d9d6cc..caac0927 100644
--- a/packages/app/src/i18n/zh.ts
+++ b/packages/app/src/i18n/zh.ts
@@ -819,8 +819,9 @@ export const dict = {
   "worktree.remove.refused": "无法删除工作树",
   "session.followupDock.summary.one": "{{count}} 条排队消息",
   "session.followupDock.summary.other": "{{count}} 条排队消息",
-  "session.followupDock.sendNow": "立即发送",
+  "session.followupDock.sendNow": "发送引导",
   "session.followupDock.edit": "编辑",
+  "session.followupDock.delete": "丢弃",
   "session.followupDock.collapse": "折叠排队消息",
   "session.followupDock.expand": "展开排队消息",
   "session.revertDock.summary.one": "{{count}} 条已回滚消息",
diff --git a/packages/app/src/pages/layout.tsx b/packages/app/src/pages/layout.tsx
index 865c1994..9cd70c53 100644
--- a/packages/app/src/pages/layout.tsx
+++ b/packages/app/src/pages/layout.tsx
@@ -2583,9 +2583,7 @@ export default function Layout(props: ParentProps) {
                   "size-full overflow-x-hidden flex flex-col items-start contain-strict border-t border-border-weak-base bg-background-base xl:border-l xl:rounded-tl-[12px]": true,
                 }}
               >
-                <Show when={!autoselecting.loading} fallback={<div class="size-full" />}>
-                  {props.children}
-                </Show>
+                {props.children}
               </main>
             </div>
 
diff --git a/packages/app/src/pages/session.tsx b/packages/app/src/pages/session.tsx
index d5254c81..c01b51eb 100644
--- a/packages/app/src/pages/session.tsx
+++ b/packages/app/src/pages/session.tsx
@@ -43,7 +43,7 @@ import { useSDK } from "@/context/sdk"
 import { useServerSDK } from "@/context/server-sdk"
 import { useSettings } from "@/context/settings"
 import { useSync } from "@/context/sync"
-import { useTerminal } from "@/context/terminal"
+import { useTerminalHosts } from "@/context/terminal"
 import { DialogDeepAgentPromptConfirm } from "@/components/dialog-deepagent-prompt-confirm"
 import {
   type DeepAgentPromptPrepareResult,
@@ -203,7 +203,7 @@ export default function Page() {
   const settings = useSettings()
   const prompt = usePrompt()
   const comments = useComments()
-  const terminal = useTerminal()
+  const terminalHosts = useTerminalHosts()
   const server = useServer()
   const navigate = useNavigate()
   const [searchParams, setSearchParams] = useSearchParams<{ prompt?: string }>()
@@ -852,15 +852,12 @@ export default function Page() {
       return
     }
 
-    // Prefer the open terminal over the composer when it can take focus
-    const terminalVisible = (() => {
-      const panel = view().panel
-      return panel.location("terminal") === "bottom"
-        ? panel.bottom.opened() && panel.bottom.activeView() === "terminal"
-        : view().rightPanel.mode() === "terminal"
-    })()
-    if (terminalVisible) {
-      const id = terminal.active()
+    // Prefer the open terminal over the composer when it can take focus.
+    // Phase 3: check both bottom and side hosts.
+    const bottomVisible = view().panel.bottom.opened() && view().panel.bottom.activeView() === "terminal"
+    const sideVisible = view().rightPanel.mode() === "terminal"
+    if (bottomVisible || sideVisible) {
+      const id = bottomVisible ? terminalHosts.bottom.active() : terminalHosts.side.active()
       if (id && shouldFocusTerminalOnKeyDown(event) && focusTerminalById(id)) return
     }
 
@@ -1447,11 +1444,10 @@ export default function Page() {
   })
 
   const followupMutation = useMutation(() => ({
-    mutationFn: async (input: { sessionID: string; id: string; manual?: boolean }) => {
+    mutationFn: async (input: { sessionID: string; id: string }) => {
       const item = (followup.items[input.sessionID] ?? []).find((entry) => entry.id === input.id)
       if (!item) return
 
-      if (input.manual) setFollowup("paused", input.sessionID, undefined)
       setFollowup("failed", input.sessionID, undefined)
 
       const ok = await sendFollowupDraft({
@@ -1469,7 +1465,7 @@ export default function Page() {
       if (!ok) return
 
       setFollowup("items", input.sessionID, (items) => (items ?? []).filter((entry) => entry.id !== input.id))
-      if (input.manual) resumeScroll()
+      resumeScroll()
     },
   }))
 
@@ -1486,7 +1482,9 @@ export default function Page() {
   const queueEnabled = createMemo(() => {
     const id = params.id
     if (!id) return false
-    return settings.general.followup() === "queue" && busy(id) && !composer.blocked() && !isChildSession()
+    // Steers are deliberate mid-turn instructions. Keep them locally editable until the
+    // user explicitly sends from the dock; only then does promptAsync admit them server-side.
+    return busy(id) && !composer.blocked() && !isChildSession()
   })
 
   const followupText = (item: FollowupDraft) => {
@@ -1517,13 +1515,13 @@ export default function Page() {
 
   const followupDock = createMemo(() => queuedFollowups().map((item) => ({ id: item.id, text: followupText(item) })))
 
-  const sendFollowup = (sessionID: string, id: string, opts?: { manual?: boolean }) => {
+  const sendFollowup = (sessionID: string, id: string) => {
     if (sync.session.get(sessionID)?.parentID) return Promise.resolve()
     const item = (followup.items[sessionID] ?? []).find((entry) => entry.id === id)
     if (!item) return Promise.resolve()
     if (followupBusy(sessionID)) return Promise.resolve()
 
-    return followupMutation.mutateAsync({ sessionID, id, manual: opts?.manual })
+    return followupMutation.mutateAsync({ sessionID, id })
   }
 
   const editFollowup = (id: string) => {
@@ -1543,6 +1541,15 @@ export default function Page() {
     })
   }
 
+  const deleteFollowup = (id: string) => {
+    const sessionID = params.id
+    if (!sessionID) return
+    if (followupBusy(sessionID)) return
+
+    setFollowup("items", sessionID, (items) => (items ?? []).filter((entry) => entry.id !== id))
+    setFollowup("failed", sessionID, (value) => (value === id ? undefined : value))
+  }
+
   const clearFollowupEdit = () => {
     const id = params.id
     if (!id) return
@@ -1664,22 +1671,6 @@ export default function Page() {
 
   const actions = { revert, fork }
 
-  createEffect(() => {
-    const sessionID = params.id
-    if (!sessionID) return
-
-    const item = queuedFollowups()[0]
-    if (!item) return
-    if (followupBusy(sessionID)) return
-    if (followup.failed[sessionID] === item.id) return
-    if (followup.paused[sessionID]) return
-    if (isChildSession()) return
-    if (composer.blocked()) return
-    if (busy(sessionID)) return
-
-    void sendFollowup(sessionID, item.id)
-  })
-
   createResizeObserver(
     () => promptDock,
     ({ height }) => {
@@ -1775,9 +1766,10 @@ export default function Page() {
                 setFollowup("paused", id, true)
               },
               onSend: (id) => {
-                void sendFollowup(params.id!, id, { manual: true })
+                void sendFollowup(params.id!, id)
               },
               onEdit: editFollowup,
+              onDelete: deleteFollowup,
               onEditLoaded: clearFollowupEdit,
             }
           : undefined
diff --git a/packages/app/src/pages/session/composer/session-composer-region.tsx b/packages/app/src/pages/session/composer/session-composer-region.tsx
index eeb8fee2..5083db31 100644
--- a/packages/app/src/pages/session/composer/session-composer-region.tsx
+++ b/packages/app/src/pages/session/composer/session-composer-region.tsx
@@ -40,6 +40,7 @@ export function SessionComposerRegion(props: {
     onAbort: () => void
     onSend: (id: string) => void
     onEdit: (id: string) => void
+    onDelete: (id: string) => void
     onEditLoaded: () => void
   }
   revert?: {
@@ -279,6 +280,7 @@ export function SessionComposerRegion(props: {
                   sending={props.followup!.sending}
                   onSend={props.followup!.onSend}
                   onEdit={props.followup!.onEdit}
+                  onDelete={props.followup!.onDelete}
                 />
               </Show>
               <Show
diff --git a/packages/app/src/pages/session/composer/session-followup-dock.tsx b/packages/app/src/pages/session/composer/session-followup-dock.tsx
index 4a76fe55..3504dc34 100644
--- a/packages/app/src/pages/session/composer/session-followup-dock.tsx
+++ b/packages/app/src/pages/session/composer/session-followup-dock.tsx
@@ -10,6 +10,7 @@ export function SessionFollowupDock(props: {
   sending?: string
   onSend: (id: string) => void
   onEdit: (id: string) => void
+  onDelete: (id: string) => void
 }) {
   const language = useLanguage()
   const [store, setStore] = createStore({
@@ -99,6 +100,15 @@ export function SessionFollowupDock(props: {
                 >
                   {language.t("session.followupDock.edit")}
                 </Button>
+                <IconButton
+                  icon="close"
+                  size="small"
+                  variant="ghost"
+                  disabled={!!props.sending}
+                  onClick={() => props.onDelete(item.id)}
+                  title={language.t("session.followupDock.delete")}
+                  aria-label={language.t("session.followupDock.delete")}
+                />
               </div>
             )}
           </For>
diff --git a/packages/app/src/pages/session/message-timeline.data.ts b/packages/app/src/pages/session/message-timeline.data.ts
index 13fc176c..4ae5e699 100644
--- a/packages/app/src/pages/session/message-timeline.data.ts
+++ b/packages/app/src/pages/session/message-timeline.data.ts
@@ -260,7 +260,9 @@ export namespace Timeline {
     }
 
     if (error) {
-      const data = error.data?.message
+      // Not every assistant error carries `data.message` (e.g. OutputDegenerationError has
+      // { chars, ratio, detectorVersion }). Read via loose-record probe.
+      const data = (error.data as Record<string, unknown> | undefined)?.message
       rows.push(
         new TimelineRow.Error({
           userMessageID: userMessage.id,
diff --git a/packages/app/src/pages/session/session-side-panel.tsx b/packages/app/src/pages/session/session-side-panel.tsx
index e225bf22..ce5bc65d 100644
--- a/packages/app/src/pages/session/session-side-panel.tsx
+++ b/packages/app/src/pages/session/session-side-panel.tsx
@@ -1,4 +1,4 @@
-import { For, Match, Show, Switch, createEffect, createMemo, createResource, createSignal, type ComponentProps, type JSX } from "solid-js"
+import { For, Match, Show, Switch, createEffect, createMemo, createSignal, type ComponentProps, type JSX } from "solid-js"
 import { createMediaQuery } from "@solid-primitives/media"
 import { Tabs } from "@deepagent-code/ui/tabs"
 import { IconButton } from "@deepagent-code/ui/icon-button"
@@ -7,6 +7,7 @@ import { Tooltip } from "@deepagent-code/ui/tooltip"
 import { ResizeHandle } from "@deepagent-code/ui/resize-handle"
 import type { SnapshotFileDiff, VcsFileDiff } from "@deepagent-code/sdk/v2"
 import { RIGHT_PANEL_RAIL_PX, type RightPanelWidthBucket, type DockPanelID } from "@/context/layout"
+import { useTerminalHosts } from "@/context/terminal"
 
 import FileTree from "@/components/file-tree"
 import { SidePanelMcp } from "@/pages/session/side-panel-mcp"
@@ -16,9 +17,7 @@ import { useDebug } from "@/context/debug"
 import { useFile, type SelectedLineRange } from "@/context/file"
 import { useLanguage } from "@/context/language"
 import { useLayout } from "@/context/layout"
-import { useSDK } from "@/context/sdk"
 import { useSync } from "@/context/sync"
-import { fetchCapabilities } from "@/components/deepagent/panel-goal.api"
 import { createOpenSessionFileTab, createSessionTabs, type Sizing } from "@/pages/session/helpers"
 import { IdeFileEditor } from "@/pages/session/ide-file-editor"
 import { setSessionHandoff } from "@/pages/session/handoff"
@@ -29,7 +28,6 @@ import { SidePanelWorktree } from "@/pages/session/side-panel-worktree"
 import { SidePanelDebug } from "@/pages/session/side-panel-debug"
 import { SidePanelProfile } from "@/pages/session/side-panel-profile"
 import { SidePanelIM } from "@/pages/session/side-panel-im"
-import { SidePanelOversight } from "@/pages/session/side-panel-oversight"
 import { SidePanelDockHeader, SidePanelTerminal, SidePanelDebugConsole } from "@/pages/session/side-panel-terminal"
 import { ProblemsPanel } from "@/pages/session/problems-panel"
 
@@ -44,7 +42,6 @@ type PanelMode =
   | "files"
   | "subagents"
   | "im"
-  | "oversight"
   | "browser"
   | "worktree"
   | "mcp"
@@ -57,9 +54,9 @@ type PanelMode =
 
 type PanelGroup = "code" | "agents" | "env" | "dev" | "dock"
 
-// Movable panel views appear in this rail only when their persisted location is
-// side. Other entries remain side-native.
-const DOCK_PANEL_MODES: readonly DockPanelID[] = ["terminal", "debug-console", "problems"]
+// Phase 3: terminal is now side-native and always visible in the rail.
+// Only debug-console and problems are still movable dock views.
+const MOVABLE_DOCK_MODES: readonly DockPanelID[] = ["debug-console", "problems"]
 
 type PanelDef = {
   readonly mode: PanelMode
@@ -70,8 +67,6 @@ type PanelDef = {
   readonly bucket: RightPanelWidthBucket
   // Keybind command id (rendered on the rail tooltip), if any.
   readonly keybind?: string
-  // Gate the entry on a server capability (T1.1). Absent ⇒ always shown.
-  readonly capability?: "oversight"
 }
 
 // Order = rail order. Groups are contiguous so the rail can draw a divider between them.
@@ -79,10 +74,9 @@ const PANELS: readonly PanelDef[] = [
   // Code
   { mode: "review", icon: "review", titleKey: "session.tab.review", group: "code", bucket: "wide", keybind: "review.toggle" },
   { mode: "files", icon: "file-tree", titleKey: "settings.general.row.showFileTree.title", group: "code", bucket: "wide", keybind: "fileTree.toggle" },
-  // Agents
+  // Agents — subagents is now the unified "子Agent监督" entry (Phase 2: oversight merged in).
   { mode: "subagents", icon: "agent-tree", titleKey: "session.subagents.title", group: "agents", bucket: "narrow" },
   { mode: "im", icon: "bubble-5", titleKey: "session.tab.im", group: "agents", bucket: "narrow" },
-  { mode: "oversight", icon: "oversight", titleKey: "session.panel.oversight", group: "agents", bucket: "narrow", capability: "oversight" },
   // Env
   { mode: "browser", icon: "window-cursor", titleKey: "browser.title", group: "env", bucket: "narrow" },
   { mode: "worktree", icon: "branch", titleKey: "worktree.title", group: "env", bucket: "narrow" },
@@ -123,39 +117,15 @@ export function SessionSidePanel(props: {
   const language = useLanguage()
   const command = useCommand()
   const sync = useSync()
-  const sdk = useSDK()
+  const terminalHosts = useTerminalHosts()
   const { params, sessionKey, tabs, view } = useSessionLayout()
 
   const isDesktop = createMediaQuery("(min-width: 768px)")
 
-  // T1.1 — gate flag-off panel entries on the server's advertised capabilities so an entry never opens
-  // a permanently-empty dead-end. The Oversight Approval Queue's producers live behind
-  // v4MultiAgentRuntime (default OFF); when it is off the queue can never be fed, so we hide the icon
-  // rather than let a user open an empty panel with no way to populate it. Tolerant of an older server
-  // (fetch fails ⇒ all V4 flags treated OFF ⇒ entry hidden).
-  const [capabilities] = createResource(() =>
-    fetchCapabilities(sdk.client as unknown as Parameters<typeof fetchCapabilities>[0]).catch(() => null),
-  )
-  const oversightEnabled = () => capabilities()?.v4MultiAgentRuntime ?? false
-
-  // T3.3 rail badge: the count of PENDING Approval-Queue items, so a supervisor sees a number on the
-  // Oversight icon without opening the panel. Only fetched when the capability is on (else the route
-  // fails-closed); best-effort — a failure just yields 0 (no badge).
-  const [oversightApprovals] = createResource(oversightEnabled, async (enabled) => {
-    if (!enabled) return 0
-    try {
-      const { fetchOversightApprovals } = await import("@/components/deepagent/oversight.api")
-      const items = await fetchOversightApprovals(sdk.client as unknown as Parameters<typeof fetchOversightApprovals>[0])
-      return items.length
-    } catch {
-      return 0
-    }
-  })
-  const oversightPendingCount = () => oversightApprovals() ?? 0
-
   // Subagents = child sessions (parentID === current). Surface a live count on the sidebar icon so
-  // the user sees a spawn happened without opening the panel; the running count (session_working)
-  // drives a pulsing badge, matching the running dot inside the panel list.
+  // the user sees a spawn happened without opening the panel.
+  // Phase 2 (§3.5): badge covers running + interrupted so the user notices any subagent that needs
+  // attention without opening the panel.
   const subagentChildren = createMemo(() => {
     const id = params.id
     if (!id) return []
@@ -164,6 +134,16 @@ export function SessionSidePanel(props: {
   const runningSubagentCount = createMemo(
     () => subagentChildren().filter((s) => sync.data.session_working(s.id)).length,
   )
+  const interruptedSubagentCount = createMemo(
+    () =>
+      subagentChildren().filter((s) => {
+        const sub = (s.metadata?.["deepagent"] as { subagent?: { interrupted?: boolean } } | undefined)?.subagent
+        return sub?.interrupted === true
+      }).length,
+  )
+  const subagentAttentionCount = createMemo(
+    () => runningSubagentCount() + interruptedSubagentCount(),
+  )
 
   // T3.1: the active panel mode (desktop only), derived once from the layout store instead of one memo
   // per panel. `isActive(mode)` and `open()` fall out of it.
@@ -307,7 +287,16 @@ export function SessionSidePanel(props: {
   const openPanel = (mode: PanelMode) => {
     view().reviewPanel.close()
     layout.fileTree.close()
-    if (DOCK_PANEL_MODES.includes(mode as DockPanelID)) {
+    // Phase 3: terminal is side-native — create a side PTY if needed, then open the panel.
+    if (mode === "terminal") {
+      if (isActive("terminal")) {
+        view().rightPanel.close()
+        return
+      }
+      view().rightPanel.open("terminal")
+      return
+    }
+    if (MOVABLE_DOCK_MODES.includes(mode as DockPanelID)) {
       view().panel.toggle(mode as DockPanelID)
       return
     }
@@ -321,20 +310,20 @@ export function SessionSidePanel(props: {
   // stays visible, so the user re-opens with one click.
   const closePanel = () => view().rightPanel.close()
 
-  // T3.1/T3.3: the rail entries, derived from PANELS — capability-gated (T1.1), with a live badge count
-  // per panel. review-change-count / running-subagent-count / oversight-pending feed `item.badge`; the
-  // rail renders whatever number is present.
+  // T3.1/T3.3: the rail entries, derived from PANELS — with a live badge count per panel.
+  // review-change-count / subagent-attention-count feed `item.badge`; the rail renders whatever
+  // number is present.
+  // Phase 2: subagent badge = running + interrupted (§3.5 — covers all states needing attention).
   const badgeFor = (mode: PanelMode): number | undefined => {
     if (mode === "review") return props.hasReview() ? props.reviewCount() : undefined
-    if (mode === "subagents") return runningSubagentCount() > 0 ? runningSubagentCount() : undefined
-    if (mode === "oversight") return oversightPendingCount() > 0 ? oversightPendingCount() : undefined
+    if (mode === "subagents") return subagentAttentionCount() > 0 ? subagentAttentionCount() : undefined
     return undefined
   }
   const railItems = createMemo(() =>
-    PANELS.filter((p) => (p.capability === "oversight" ? oversightEnabled() : true))
-      // Dock panels (terminal / debug-console) only appear in the rail when docked to the side; when
-      // in the bottom dock they're reached there instead.
-      .filter((p) => (DOCK_PANEL_MODES.includes(p.mode as DockPanelID) ? view().panel.location(p.mode as DockPanelID) === "side" : true))
+    PANELS
+      // Phase 3: terminal is side-native — always show in the rail.
+      // Other movable dock panels (debug-console, problems) only appear when docked to the side.
+      .filter((p) => (MOVABLE_DOCK_MODES.includes(p.mode as DockPanelID) ? view().panel.location(p.mode as DockPanelID) === "side" : true))
       .map((p) => ({
         ...p,
         title: language.t(p.titleKey),
@@ -581,11 +570,8 @@ export function SessionSidePanel(props: {
               <Match when={isActive("im")}>
                 <SidePanelIM onClose={closePanel} />
               </Match>
-              <Match when={isActive("oversight")}>
-                <SidePanelOversight onClose={closePanel} />
-              </Match>
               <Match when={isActive("terminal")}>
-                <SidePanelTerminal onClose={() => view().panel.toggle("terminal")} />
+                <SidePanelTerminal onClose={() => view().rightPanel.close()} />
               </Match>
               <Match when={isActive("debug-console")}>
                 <SidePanelDebugConsole onClose={() => view().panel.toggle("debug-console")} />
diff --git a/packages/app/src/pages/session/side-panel-subagents.tsx b/packages/app/src/pages/session/side-panel-subagents.tsx
index f52327fe..801e13ad 100644
--- a/packages/app/src/pages/session/side-panel-subagents.tsx
+++ b/packages/app/src/pages/session/side-panel-subagents.tsx
@@ -1,9 +1,18 @@
-import { Component, createMemo, For, Show } from "solid-js"
+import { Component, createMemo, createResource, createSignal, For, Show } from "solid-js"
 import { useSync } from "@/context/sync"
 import { useLanguage } from "@/context/language"
 import { IconButton } from "@deepagent-code/ui/icon-button"
 import { useNavigate, useParams } from "@solidjs/router"
+import { useSDK } from "@/context/sdk"
+import { fetchCapabilities } from "@/components/deepagent/panel-goal.api"
+import { OversightDashboard } from "@/components/deepagent/oversight-dashboard"
 
+// Phase 2 (§3): SidePanelSubagents is now the single "子Agent监督" entry for the right rail.
+// It holds a `selectedSessionID` to track which subagent is being inspected; that selection
+// drives the embedded OversightDashboard (takeover, rollback, trace) when the
+// v4MultiAgentRuntime capability is on. The oversight content is capability-gated: when the
+// capability is off only the basic subagent list is shown.
+//
 // U4 (S1 §P1): subagent list panel. Subagents = child sessions (Session.parentID === current). The
 // task tool already spawns them and the app already receives session.created/updated events with
 // parentID; this surfaces them as a list with status + click-to-open. Plan-step linkage is shown
@@ -19,7 +28,17 @@ export const SidePanelSubagents: Component<{ onClose: () => void }> = (props) =>
   const language = useLanguage()
   const navigate = useNavigate()
   const params = useParams()
+  const sdk = useSDK()
+
+  // ── capability gate ─────────────────────────────────────────────────────────
+  // v4MultiAgentRuntime ON ⇒ show the oversight section; OFF ⇒ basic subagent list only.
+  // Tolerant of an older server (fetch fails ⇒ capability treated OFF).
+  const [capabilities] = createResource(() =>
+    fetchCapabilities(sdk.client as unknown as Parameters<typeof fetchCapabilities>[0]).catch(() => null),
+  )
+  const oversightEnabled = () => capabilities()?.v4MultiAgentRuntime ?? false
 
+  // ── subagent list ───────────────────────────────────────────────────────────
   const children = createMemo(() => {
     const id = params.id
     if (!id) return []
@@ -32,27 +51,59 @@ export const SidePanelSubagents: Component<{ onClose: () => void }> = (props) =>
   // in the child session's metadata (`deepagent.subagent.finished`) so a completed subagent reads as
   // "finished" (read-only) instead of "idle" (looks available). `session_working` is the live signal
   // for the brief window it's actually running; the persisted marker wins once set.
+  // Phase 2 adds "interrupted" for subagents that were manually stopped.
   const isFinished = (child: { metadata?: Record<string, unknown> }): boolean => {
     const sub = (child.metadata?.["deepagent"] as { subagent?: { finished?: boolean } } | undefined)?.subagent
     return sub?.finished === true
   }
-  const statusOf = (child: { id: string; metadata?: Record<string, unknown> }): "running" | "finished" | "idle" => {
+  const isInterrupted = (child: { metadata?: Record<string, unknown> }): boolean => {
+    const sub = (child.metadata?.["deepagent"] as { subagent?: { interrupted?: boolean } } | undefined)?.subagent
+    return sub?.interrupted === true
+  }
+  const statusOf = (
+    child: { id: string; metadata?: Record<string, unknown> },
+  ): "running" | "finished" | "interrupted" | "idle" => {
     if (sync.data.session_working(child.id)) return "running"
+    if (isInterrupted(child)) return "interrupted"
     if (isFinished(child)) return "finished"
     return "idle"
   }
-  const statusLabel = (state: "running" | "finished" | "idle") =>
+  const statusLabel = (state: "running" | "finished" | "interrupted" | "idle") =>
     language.t(
       state === "running"
         ? "session.subagents.running"
         : state === "finished"
           ? "session.subagents.finished"
-          : "session.subagents.idle",
+          : state === "interrupted"
+            ? "session.subagents.interrupted"
+            : "session.subagents.idle",
     )
 
+  // ── selected session (監督対象) ───────────────────────────────────────────────
+  // §3.4.1: auto-select priority — running → interrupted → most-recent.
+  // Clicking a row sets an explicit override; clicking again deselects back to auto.
+  const defaultSelected = createMemo<string | undefined>(() => {
+    const list = children()
+    if (list.length === 0) return undefined
+    const running = list.find((s) => sync.data.session_working(s.id))
+    if (running) return running.id
+    const interrupted = list.find((s) => isInterrupted(s))
+    if (interrupted) return interrupted.id
+    return list[0].id
+  })
+
+  // null means "follow auto"; a string means the user explicitly picked this row.
+  const [explicitSelected, setExplicitSelected] = createSignal<string | undefined>(undefined)
+  const selectedSessionID = createMemo(() => explicitSelected() ?? defaultSelected())
+
+  const selectRow = (id: string) => {
+    // §3.4.2: clicking a row selects it without navigating away. [Open] button navigates.
+    setExplicitSelected((prev) => (prev === id ? undefined : id))
+  }
+
   return (
     <div class="h-full w-full min-w-0 overflow-y-auto bg-background-base">
-      <div class="sticky top-0 z-10 h-10 flex items-center justify-between px-3 bg-background-base">
+      <div class="sticky top-0 z-10 h-10 flex items-center justify-between px-3 bg-background-base border-b border-border-weaker-base">
         <span class="text-12-medium text-text">{language.t("session.subagents.title")}</span>
         <IconButton
           icon="close-small"
@@ -62,6 +113,8 @@ export const SidePanelSubagents: Component<{ onClose: () => void }> = (props) =>
           aria-label={language.t("common.close")}
         />
       </div>
+
+      {/* ── Subagent list ── */}
       <Show
         when={children().length > 0}
         fallback={
@@ -72,32 +125,72 @@ export const SidePanelSubagents: Component<{ onClose: () => void }> = (props) =>
       >
         <div class="flex flex-col gap-1 px-2 py-2">
           <For each={children()}>
-            {(child) => (
-              <button
-                type="button"
-                class="w-full flex items-center justify-between gap-2 rounded-md px-2 py-2 text-left hover:bg-background-stronger"
-                // The router nests every session route under a required `:dir` segment
-                // (`/:dir/session/:id`). Navigating to a bare `/session/${id}` matches no child
-                // route and renders a blank (black) panel. `params.dir` is the parent's dir and
-                // the subagent lives in the same scope, so it's the correct prefix — matching every
-                // other session navigation in the app (message-timeline, session-composer, etc.).
-                onClick={() => navigate(`/${params.dir}/session/${child.id}`)}
-              >
-                <div class="flex flex-col gap-0.5 min-w-0">
-                  <span class="truncate text-12-regular text-text">{child.title || child.id}</span>
-                  <span class="text-11-regular text-text-weaker">{statusLabel(statusOf(child))}</span>
+            {(child) => {
+              const status = () => statusOf(child)
+              const isSelected = () => selectedSessionID() === child.id
+              return (
+                <div
+                  class="w-full rounded-md px-2 py-2 text-left"
+                  classList={{
+                    "bg-surface-raised-base-active ring-1 ring-border-strong-base": isSelected(),
+                    "hover:bg-background-stronger": !isSelected(),
+                  }}
+                >
+                  {/* §3.4.2: click the row body to select; [Open] navigates. */}
+                  <button
+                    type="button"
+                    class="w-full flex items-center justify-between gap-2 text-left"
+                    onClick={() => selectRow(child.id)}
+                  >
+                    <div class="flex flex-col gap-0.5 min-w-0">
+                      <span class="truncate text-12-regular text-text">{child.title || child.id}</span>
+                      <span class="text-11-regular text-text-weaker">{statusLabel(status())}</span>
+                    </div>
+                    <div class="flex items-center gap-1.5 shrink-0">
+                      <Show when={status() === "running"}>
+                        <span
+                          class="h-2 w-2 rounded-full bg-text-success"
+                          style={{ animation: "var(--animate-pulse-scale)" }}
+                        />
+                      </Show>
+                      <Show when={status() === "interrupted"}>
+                        <span class="h-2 w-2 rounded-full bg-text-warning" />
+                      </Show>
+                      {/* §3.4.3: [Open] button navigates to the subagent's full session. */}
+                      <button
+                        type="button"
+                        class="text-11-regular text-text-link hover:underline px-1"
+                        onClick={(e) => {
+                          e.stopPropagation()
+                          // The router nests every session route under a required `:dir` segment
+                          // (`/:dir/session/:id`). `params.dir` is the parent's dir and the
+                          // subagent lives in the same scope — matching every other session
+                          // navigation in the app (message-timeline, session-composer, etc.).
+                          navigate(`/${params.dir}/session/${child.id}`)
+                        }}
+                      >
+                        {language.t("session.subagents.open")}
+                      </button>
+                    </div>
+                  </button>
                 </div>
-                <Show when={statusOf(child) === "running"}>
-                  <span
-                    class="h-2 w-2 shrink-0 rounded-full bg-text-success"
-                    style={{ animation: "var(--animate-pulse-scale)" }}
-                  />
-                </Show>
-              </button>
-            )}
+              )
+            }}
           </For>
         </div>
       </Show>
+
+      {/* ── Oversight section (capability-gated) ── */}
+      {/* §3.4.6: when v4MultiAgentRuntime is off hide workspace-level metrics/approval/trace
+          but keep the basic list above visible at all times. */}
+      <Show when={oversightEnabled() && selectedSessionID()}>
+        <div class="border-t border-border-weaker-base">
+          <OversightDashboard
+            selectedSessionID={selectedSessionID()}
+            onSessionSelect={(sid) => setExplicitSelected(sid)}
+          />
+        </div>
+      </Show>
     </div>
   )
 }
diff --git a/packages/app/src/pages/session/side-panel-terminal.tsx b/packages/app/src/pages/session/side-panel-terminal.tsx
index 0b95856d..2f3bb23d 100644
--- a/packages/app/src/pages/session/side-panel-terminal.tsx
+++ b/packages/app/src/pages/session/side-panel-terminal.tsx
@@ -1,75 +1,56 @@
 import { Show } from "solid-js"
 import { IconButton } from "@deepagent-code/ui/icon-button"
-import { Tooltip } from "@deepagent-code/ui/tooltip"
 
 import { useLanguage } from "@/context/language"
 import { type DockPanelID } from "@/context/layout"
-import { useTerminal } from "@/context/terminal"
-import { useSessionLayout } from "@/pages/session/session-layout"
-import { DebugConsole, TerminalActions, TerminalPanes } from "@/pages/session/terminal-view"
+import { SideTerminalProvider, useTerminal } from "@/context/terminal"
+import { DebugConsole, TerminalActions, TerminalPanes, useTerminalLifecycle } from "@/pages/session/terminal-view"
 import type { JSX } from "solid-js"
 
-/** Shared header strip for a dock panel hosted in the SIDE panel: a title, optional actions, a
- *  "move to bottom dock" button, and the panel's close button. Mirrors the bottom dock's strip so the
- *  two locations feel identical. */
-export function SidePanelDockHeader(props: {
-  id: DockPanelID
-  title: string
-  onClose: () => void
-  actions?: () => JSX.Element
-}) {
+// ---------------------------------------------------------------------------
+// SidePanelTerminal — side-native terminal host.
+// Independent from the bottom dock. Move-to-bottom / move-to-side buttons are
+// intentionally removed per Phase 3 design (§5.5).
+// ---------------------------------------------------------------------------
+
+function SidePanelTerminalContent(props: { onClose: () => void }) {
   const language = useLanguage()
-  const { view } = useSessionLayout()
-  const move = () => view().panel.move(props.id, "bottom")
+  const terminal = useTerminal()
+
+  // Lifecycle: auto-create first PTY when side panel opens; close panel when empty.
+  useTerminalLifecycle({
+    active: () => true,
+    close: props.onClose,
+    rootEl: () => document.querySelector<HTMLElement>('[data-terminal-host="side"]') ?? undefined,
+  })
+
   return (
-    <div class="flex h-9 shrink-0 items-center overflow-hidden border-b border-border-weaker-base bg-background-stronger">
-      <div class="min-w-0 flex-1 truncate px-3 text-13-regular text-text-stronger">{props.title}</div>
-      <div class="flex h-full shrink-0 items-center gap-0.5 whitespace-nowrap px-1">
-        <Show when={props.actions}>{(actions) => actions()()}</Show>
-        <div class="h-4 w-px shrink-0 bg-border-weaker-base" aria-hidden="true" />
-        <Tooltip value={language.t("dock.moveToBottom")}>
+    <div class="h-full w-full min-w-0 flex flex-col overflow-hidden bg-background-stronger">
+      {/* Simple header — no move button */}
+      <div class="flex h-9 shrink-0 items-center overflow-hidden border-b border-border-weaker-base bg-background-stronger">
+        <div class="min-w-0 flex-1 truncate px-3 text-13-regular text-text-stronger">
+          {language.t("terminal.dock.terminal")}
+        </div>
+        <div class="flex h-full shrink-0 items-center gap-0.5 whitespace-nowrap px-1">
+          <TerminalActions />
+          <div class="h-4 w-px shrink-0 bg-border-weaker-base" aria-hidden="true" />
           <IconButton
-            icon="layout-bottom"
+            icon="close-small"
             variant="ghost"
             iconSize="normal"
-            onClick={move}
-            aria-label={language.t("dock.moveToBottom")}
+            onClick={props.onClose}
+            aria-label={language.t("common.close")}
           />
-        </Tooltip>
-        <IconButton
-          icon="close-small"
-          variant="ghost"
-          iconSize="normal"
-          onClick={props.onClose}
-          aria-label={language.t("common.close")}
-        />
+        </div>
       </div>
-    </div>
-  )
-}
-
-/** Terminal hosted in the right side panel. PTY lifecycle is owned by TerminalPanel;
- * this component only provides the side-panel host. */
-export function SidePanelTerminal(props: {
-  onClose: () => void
-}) {
-  const language = useLanguage()
-  const terminal = useTerminal()
-  const { view } = useSessionLayout()
-  const terminalReady = () => view().panel.location("terminal") === "side" && terminal.ready()
-
-  return (
-    <div class="h-full w-full min-w-0 flex flex-col overflow-hidden bg-background-stronger">
-      <SidePanelDockHeader
-        id="terminal"
-        title={language.t("terminal.dock.terminal")}
-        onClose={props.onClose}
-        actions={() => <TerminalActions />}
-      />
       <div class="relative min-h-0 flex-1" data-terminal-host="side">
         <Show
-          when={terminalReady()}
-          fallback={<div class="size-full flex items-center justify-center text-13-regular text-text-weak">{language.t("terminal.loading")}</div>}
+          when={terminal.ready()}
+          fallback={
+            <div class="size-full flex items-center justify-center text-13-regular text-text-weak">
+              {language.t("terminal.loading")}
+            </div>
+          }
         >
           <TerminalPanes />
         </Show>
@@ -78,6 +59,20 @@ export function SidePanelTerminal(props: {
   )
 }
 
+/** Side-panel terminal host. Wraps in SideTerminalProvider so all terminal-view
+ *  components target the side session independently of the bottom dock. */
+export function SidePanelTerminal(props: { onClose: () => void }) {
+  return (
+    <SideTerminalProvider>
+      <SidePanelTerminalContent onClose={props.onClose} />
+    </SideTerminalProvider>
+  )
+}
+
+// ---------------------------------------------------------------------------
+// SidePanelDebugConsole — unchanged, debug console is not dual-host.
+// ---------------------------------------------------------------------------
+
 /** Debug console hosted in the right side panel. */
 export function SidePanelDebugConsole(props: { onClose: () => void }) {
   const language = useLanguage()
@@ -90,3 +85,37 @@ export function SidePanelDebugConsole(props: { onClose: () => void }) {
     </div>
   )
 }
+
+// ---------------------------------------------------------------------------
+// SidePanelDockHeader — retained for non-terminal dock panels (debug-console,
+// problems) that session-side-panel.tsx uses directly.
+// "Move to bottom" button removed per Phase 3 §5.5.
+// ---------------------------------------------------------------------------
+
+/** Shared header strip for a dock panel hosted in the SIDE panel.
+ *  "Move to bottom" button has been removed — bottom and side are now independent. */
+export function SidePanelDockHeader(props: {
+  id: DockPanelID
+  title: string
+  onClose: () => void
+  actions?: () => JSX.Element
+}) {
+  const language = useLanguage()
+  return (
+    <div class="flex h-9 shrink-0 items-center overflow-hidden border-b border-border-weaker-base bg-background-stronger">
+      <div class="min-w-0 flex-1 truncate px-3 text-13-regular text-text-stronger">{props.title}</div>
+      <div class="flex h-full shrink-0 items-center gap-0.5 whitespace-nowrap px-1">
+        <Show when={props.actions}>{(actions) => actions()()}</Show>
+        <div class="h-4 w-px shrink-0 bg-border-weaker-base" aria-hidden="true" />
+        <IconButton
+          icon="close-small"
+          variant="ghost"
+          iconSize="normal"
+          onClick={props.onClose}
+          aria-label={language.t("common.close")}
+        />
+      </div>
+    </div>
+  )
+}
+
diff --git a/packages/app/src/pages/session/terminal-panel.tsx b/packages/app/src/pages/session/terminal-panel.tsx
index c7cd9d72..fe9fa8cc 100644
--- a/packages/app/src/pages/session/terminal-panel.tsx
+++ b/packages/app/src/pages/session/terminal-panel.tsx
@@ -7,7 +7,7 @@ import { IconButton } from "@deepagent-code/ui/icon-button"
 import { Tooltip } from "@deepagent-code/ui/tooltip"
 import { useLanguage } from "@/context/language"
 import { useLayout, type DockPanelID } from "@/context/layout"
-import { useTerminal } from "@/context/terminal"
+import { BottomTerminalProvider, useTerminal } from "@/context/terminal"
 import { terminalTabLabel } from "@/pages/session/terminal-label"
 import { createSizing } from "@/pages/session/helpers"
 import { setTerminalHandoff } from "@/pages/session/handoff"
@@ -22,7 +22,8 @@ type Props = {
   onOpenFile: (path: string, line: number) => void
 }
 
-export function TerminalPanel(props: Props) {
+/** Inner content rendered under BottomTerminalProvider context. */
+function TerminalPanelContent(props: Props) {
   const layout = useLayout()
   const terminal = useTerminal()
   const language = useLanguage()
@@ -32,6 +33,8 @@ export function TerminalPanel(props: Props) {
   const panel = () => view().panel
   const opened = createMemo(() => panel().bottom.opened())
   const active = createMemo(() => panel().bottom.activeView())
+  // Bottom panel only shows the non-terminal dock panels (debug-console, problems).
+  // Terminal is no longer a movable dock view — it is bottom-native here.
   const bottomTabs = createMemo<DockPanelID[]>(() => panel().viewsAt("bottom"))
   const visible = createMemo(() => opened())
   const [store, setStore] = createStore({
@@ -42,20 +45,17 @@ export function TerminalPanel(props: Props) {
   const max = () => store.view * 0.6
   const pane = () => Math.min(height(), max())
   const close = () => panel().bottom.toggle()
-  const terminalVisible = createMemo(() => {
-    const current = panel()
-    return current.location("terminal") === "bottom"
-      ? current.bottom.opened() && current.bottom.activeView() === "terminal"
-      : view().rightPanel.mode() === "terminal"
-  })
 
-  // This is the only lifecycle owner. Exactly one visible host mounts the pane
-  // tree; moving the panel reconnects renderers to the same runtime PTYs.
+  // Bottom terminal is visible when the bottom panel is open with terminal as active view.
+  const terminalVisible = createMemo(() =>
+    panel().bottom.opened() && panel().bottom.activeView() === "terminal",
+  )
+
+  // Lifecycle owner for the bottom host — auto-creates, auto-focuses, closes panel when empty.
   useTerminalLifecycle({
     active: terminalVisible,
     close: () => panel().toggle("terminal"),
-    rootEl: () =>
-      document.querySelector<HTMLElement>('[data-terminal-host="bottom"], [data-terminal-host="side"]') ?? root,
+    rootEl: () => document.querySelector<HTMLElement>('[data-terminal-host="bottom"]') ?? root,
   })
 
   onMount(() => {
@@ -149,20 +149,7 @@ export function TerminalPanel(props: Props) {
               <Show when={active() === "terminal"}>
                 <div class="h-4 w-px shrink-0 bg-border-weaker-base" aria-hidden="true" />
               </Show>
-              <Show when={active() && panel().sideAvailable()}>
-                <Tooltip value={language.t("session.panel.moveToSide")}>
-                  <IconButton
-                    icon="layout-right"
-                    variant="ghost"
-                    iconSize="normal"
-                    aria-label={language.t("session.panel.moveToSide")}
-                    onClick={() => {
-                      const current = active()
-                      if (current) panel().move(current, "side")
-                    }}
-                  />
-                </Tooltip>
-              </Show>
+              {/* "Move to side" button removed — bottom and side are now independent hosts. */}
               <Tooltip value={language.t("common.close")}>
                 <IconButton
                   icon="close"
@@ -178,22 +165,8 @@ export function TerminalPanel(props: Props) {
             <Show
               when={active()}
               fallback={
-                <div class="size-full flex flex-col items-center justify-center gap-2 text-13-regular text-text-weak">
+                <div class="size-full flex items-center justify-center text-13-regular text-text-weak">
                   <div>{language.t("session.panel.emptyBottom")}</div>
-                  <For
-                    each={(["terminal", "debug-console", "problems"] as DockPanelID[]).filter(
-                      (id) => panel().location(id) === "side",
-                    )}
-                  >
-                    {(id) => (
-                      <button
-                        class="text-13-medium text-text-info hover:underline"
-                        onClick={() => panel().move(id, "bottom")}
-                      >
-                        {language.t(PANEL_META[id].titleKey)}
-                      </button>
-                    )}
-                  </For>
                 </div>
               }
             >
@@ -228,3 +201,13 @@ export function TerminalPanel(props: Props) {
     </div>
   )
 }
+
+/** Bottom-dock terminal panel. Provides the BottomTerminalProvider context so all
+ *  terminal-view components (TerminalPanes, TerminalActions, …) target the bottom session. */
+export function TerminalPanel(props: Props) {
+  return (
+    <BottomTerminalProvider>
+      <TerminalPanelContent {...props} />
+    </BottomTerminalProvider>
+  )
+}
diff --git a/packages/app/src/pages/session/terminal-view.tsx b/packages/app/src/pages/session/terminal-view.tsx
index e218c0d3..51f95c3e 100644
--- a/packages/app/src/pages/session/terminal-view.tsx
+++ b/packages/app/src/pages/session/terminal-view.tsx
@@ -245,8 +245,8 @@ function LeafPane(props: { node: PaneLeaf }) {
           >
             <For each={ptys()}>
               {(pty) => (
-                <Show when={activeId() === pty.id}>
-                  <TerminalSessionView pty={pty} focused={focused()} />
+                <Show when={activeId() === pty.id && pty} keyed>
+                  {(activePty) => <TerminalSessionView pty={activePty} focused={focused()} />}
                 </Show>
               )}
             </For>
@@ -374,7 +374,9 @@ export function TerminalPanes() {
   const terminal = useTerminal()
   return (
     <div class="absolute inset-0 flex">
-      <PaneRenderer node={terminal.root()} />
+      <Show when={terminal.root()} keyed>
+        {(node) => <PaneRenderer node={node} />}
+      </Show>
     </div>
   )
 }
@@ -393,32 +395,38 @@ export function useTerminalLifecycle(opts: {
 }) {
   const terminal = useTerminal()
   const [autoCreated, setAutoCreated] = createSignal(false)
+  const [closing, setClosing] = createSignal(false)
+
+  createEffect(
+    on(
+      () => terminal.closeRequest(),
+      (request, previous) => {
+        if (previous === undefined || request === previous) return
+        if (!opts.active()) return
+        // pty.deleted clears the final tab before this effect runs. Mark the host as closing
+        // before hiding it so the empty-state effect cannot recreate a PTY during unmount.
+        setClosing(true)
+        opts.close()
+      },
+    ),
+  )
 
   createEffect(() => {
     if (!opts.active()) {
       setAutoCreated(false)
+      setClosing(false)
       return
     }
+    if (closing()) return
     if (terminal.all().length !== 0) {
       setAutoCreated(false)
       return
     }
     if (!terminal.ready() || terminal.creating() || terminal.createError() || autoCreated()) return
-    void terminal.new()
     setAutoCreated(true)
+    void terminal.new()
   })
 
-  createEffect(
-    on(
-      () => terminal.closeRequest(),
-      (request, previous) => {
-        if (previous === undefined || request === previous) return
-        if (!opts.active()) return
-        opts.close()
-      },
-    ),
-  )
-
   const focus = (id: string) => {
     focusTerminalById(id)
     const frame = requestAnimationFrame(() => {
diff --git a/packages/app/src/pages/session/use-session-commands.tsx b/packages/app/src/pages/session/use-session-commands.tsx
index 6039179f..4eb4a98f 100644
--- a/packages/app/src/pages/session/use-session-commands.tsx
+++ b/packages/app/src/pages/session/use-session-commands.tsx
@@ -10,7 +10,7 @@ import { usePermission } from "@/context/permission"
 import { usePrompt } from "@/context/prompt"
 import { useSDK } from "@/context/sdk"
 import { useSync } from "@/context/sync"
-import { useTerminal } from "@/context/terminal"
+import { useTerminalHosts } from "@/context/terminal"
 import { showToast } from "@/utils/toast"
 import { findLast } from "@deepagent-code/core/util/array"
 import { createSessionTabs } from "@/pages/session/helpers"
@@ -43,7 +43,7 @@ export const useSessionCommands = (actions: SessionCommandContext) => {
   const prompt = usePrompt()
   const sdk = useSDK()
   const sync = useSync()
-  const terminal = useTerminal()
+  const terminalHosts = useTerminalHosts()
   const layout = useLayout()
   const navigate = useNavigate()
   const { params, tabs, view } = useSessionLayout()
@@ -259,8 +259,9 @@ export const useSessionCommands = (actions: SessionCommandContext) => {
     addSelectionToContext(path, selectionFromLines(range))
   }
 
+  // Phase 3: openTerminal always creates in the bottom host and opens the bottom panel.
   const openTerminal = () => {
-    terminal.new()
+    void terminalHosts.bottom.new()
     view().panel.reveal("terminal")
   }
 
@@ -518,7 +519,7 @@ export const useSessionCommands = (actions: SessionCommandContext) => {
       title: language.t("command.problems.reveal"),
       onSelect: () => view().panel.reveal("problems"),
     }),
-    ...(["terminal", "debug-console", "problems"] as const).flatMap((id) => {
+    ...(["debug-console", "problems"] as const).flatMap((id) => {
       const label = language.t(`session.panel.${id === "debug-console" ? "debugConsole" : id}`)
       const location = view().panel.location(id)
       return [
@@ -541,6 +542,12 @@ export const useSessionCommands = (actions: SessionCommandContext) => {
         }),
       ]
     }),
+    // Phase 3: terminal show command always opens bottom terminal (no move commands).
+    viewCommand({
+      id: "panel.terminal.show",
+      title: `${language.t("session.panel.showView")}: ${language.t("session.panel.terminal")}`,
+      onSelect: () => view().panel.reveal("terminal"),
+    }),
     viewCommand({
       id: "review.toggle",
       title: language.t("command.review.toggle"),
@@ -569,13 +576,14 @@ export const useSessionCommands = (actions: SessionCommandContext) => {
     }),
   ]
 
-  const terminalOpen = () => {
-    const panel = view().panel
-    return panel.location("terminal") === "bottom"
-      ? panel.bottom.opened() && panel.bottom.activeView() === "terminal"
-      : view().rightPanel.mode() === "terminal"
-  }
-  const focusedPane = () => terminal.focusedPaneId()
+  // Phase 3: terminal commands route to the bottom host. The side terminal is
+  // opened from the right-panel rail (session-side-panel.tsx) rather than commands.
+  const bottomTerminalOpen = () =>
+    view().panel.bottom.opened() && view().panel.bottom.activeView() === "terminal"
+  const sideTerminalOpen = () => view().rightPanel.mode() === "terminal"
+  const terminalOpen = () => bottomTerminalOpen() || sideTerminalOpen()
+  // Keybind commands operate on the bottom terminal session.
+  const focusedPane = () => terminalHosts.bottom.focusedPaneId()
   const terminalCmds = () => [
     terminalCommand({
       id: "terminal.new",
@@ -585,53 +593,47 @@ export const useSessionCommands = (actions: SessionCommandContext) => {
       onSelect: openTerminal,
     }),
     terminalCommand({
-      // V3.7 review P1-1: split/close moved to the ctrl+alt+* family (matching
-      // terminal.new's ctrl+alt+t) to avoid colliding with fileTree.toggle (mod+\)
-      // and tab.close (mod+w) — mod resolves to ctrl on non-Mac, so ctrl+\/ctrl+w
-      // were being preempted by the earlier-registered view/file commands.
-      // Only a left/right (side-by-side) split is exposed. Keep the command and
-      // toolbar on the same direction so both entry points have identical layout.
       id: "terminal.split",
       title: language.t("command.terminal.split"),
       description: language.t("command.terminal.split.description"),
       keybind: "ctrl+alt+\\",
-      disabled: !terminalOpen() || !terminal.canSplit(focusedPane()),
-      onSelect: () => terminal.split("horizontal"),
+      disabled: !bottomTerminalOpen() || !terminalHosts.bottom.canSplit(focusedPane()),
+      onSelect: () => void terminalHosts.bottom.split("horizontal"),
     }),
     terminalCommand({
       id: "terminal.closePane",
       title: language.t("command.terminal.closePane"),
       keybind: "ctrl+alt+w",
-      disabled: !terminalOpen(),
-      onSelect: () => void terminal.closePane(focusedPane()),
+      disabled: !bottomTerminalOpen(),
+      onSelect: () => void terminalHosts.bottom.closePane(focusedPane()),
     }),
     terminalCommand({
       id: "terminal.focus.left",
       title: language.t("command.terminal.focus.left"),
       keybind: "ctrl+arrowleft",
-      disabled: !terminalOpen(),
-      onSelect: () => terminal.focusNeighbor("left"),
+      disabled: !bottomTerminalOpen(),
+      onSelect: () => terminalHosts.bottom.focusNeighbor("left"),
     }),
     terminalCommand({
       id: "terminal.focus.right",
       title: language.t("command.terminal.focus.right"),
       keybind: "ctrl+arrowright",
-      disabled: !terminalOpen(),
-      onSelect: () => terminal.focusNeighbor("right"),
+      disabled: !bottomTerminalOpen(),
+      onSelect: () => terminalHosts.bottom.focusNeighbor("right"),
     }),
     terminalCommand({
       id: "terminal.focus.up",
       title: language.t("command.terminal.focus.up"),
       keybind: "ctrl+arrowup",
-      disabled: !terminalOpen(),
-      onSelect: () => terminal.focusNeighbor("up"),
+      disabled: !bottomTerminalOpen(),
+      onSelect: () => terminalHosts.bottom.focusNeighbor("up"),
     }),
     terminalCommand({
       id: "terminal.focus.down",
       title: language.t("command.terminal.focus.down"),
       keybind: "ctrl+arrowdown",
-      disabled: !terminalOpen(),
-      onSelect: () => terminal.focusNeighbor("down"),
+      disabled: !bottomTerminalOpen(),
+      onSelect: () => terminalHosts.bottom.focusNeighbor("down"),
     }),
   ]
 
diff --git a/packages/core/src/database/database.ts b/packages/core/src/database/database.ts
index c61c45be..b0bf6a6a 100644
--- a/packages/core/src/database/database.ts
+++ b/packages/core/src/database/database.ts
@@ -29,7 +29,8 @@ export const layer = Layer.effect(
     yield* db.run("PRAGMA busy_timeout = 5000")
     yield* db.run("PRAGMA cache_size = -64000")
     yield* db.run("PRAGMA foreign_keys = ON")
-    yield* db.run("PRAGMA wal_checkpoint(PASSIVE)")
+    // wal_checkpoint removed from startup: it blocked the "ready" signal by 1-3 s
+    // on large databases. SQLite auto-checkpoints at wal_autocheckpoint = 1000 pages.
     yield* DatabaseMigration.apply(db)
 
     return { db }
diff --git a/packages/core/src/deepagent/deepagent-event-bus.ts b/packages/core/src/deepagent/deepagent-event-bus.ts
index ce767806..5f11eab5 100644
--- a/packages/core/src/deepagent/deepagent-event-bus.ts
+++ b/packages/core/src/deepagent/deepagent-event-bus.ts
@@ -247,10 +247,8 @@ export const layerWith = (options?: LayerOptions) =>
       )
 
       // §A3 at-least-once — the set of consumer groups with a live `subscribe({group})` stream, and
-      // the type filter each declared. `publish` writes a durable `pending` delivery row for every
-      // group whose filter matches, so an event owed to a group survives a crash between receipt and
-      // ack (recoverable via `dueRetries`). Ref-counted: a group is registered while ≥1 of its streams
-      // is live and dropped when the last unsubscribes, so we never accrue deliveries no one consumes.
+      // the type filter each declared. Durable registration is independent of this live bookkeeping:
+      // a temporarily offline consumer must remain owed matching events until it restarts.
       const groups = new Map<string, { types: Map<string | null, number> }>()
       const registerGroup = (group: string, type: string | null) =>
         Effect.sync(() => {
@@ -480,9 +478,7 @@ export const layerWith = (options?: LayerOptions) =>
             ),
           ),
           Stream.ensuring(
-            Effect.all([unregisterGroup(group, type), touchLastSeen], { concurrency: "unbounded" }).pipe(
-              Effect.asVoid,
-            ),
+            Effect.all([unregisterGroup(group, type), touchLastSeen], { concurrency: "unbounded" }).pipe(Effect.asVoid),
           ),
         )
       }
diff --git a/packages/deepagent-code/src/cli/cmd/mcp.ts b/packages/deepagent-code/src/cli/cmd/mcp.ts
index 3280e3c7..9459afbb 100644
--- a/packages/deepagent-code/src/cli/cmd/mcp.ts
+++ b/packages/deepagent-code/src/cli/cmd/mcp.ts
@@ -13,6 +13,7 @@ import { McpOAuthProvider } from "../../mcp/oauth-provider"
 import { Config } from "@/config/config"
 import { ConfigMCPV1 } from "@deepagent-code/core/v1/config/mcp"
 import { InstanceRef } from "@/effect/instance-ref"
+import { AppRuntime } from "@/effect/app-runtime"
 import { InstallationVersion } from "@deepagent-code/core/installation/version"
 import path from "path"
 import { Global } from "@deepagent-code/core/global"
@@ -507,9 +508,18 @@ export const McpAddCommand = effectCmd({
               ...(Object.keys(environment).length ? { environment } : {}),
             }
 
-        const configPath = await resolveConfigPath(Global.Path.config, true)
-        await addMcpToConfig(args.name, mcpConfig, configPath)
-        prompts.log.success(`MCP server "${args.name}" added to ${configPath}`)
+        const config = await AppRuntime.runPromise(Config.Service)
+        const current = await AppRuntime.runPromise(config.getGlobal())
+        await AppRuntime.runPromise(
+          config.updateGlobal({
+            ...current,
+            mcp: {
+              ...current.mcp,
+              [args.name]: mcpConfig,
+            },
+          }),
+        )
+        prompts.log.success(`MCP server "${args.name}" added to ${path.join(Global.Path.config, "config.jsonc")}`)
         return
       }
 
diff --git a/packages/deepagent-code/src/panel/panel-convene-consumer.ts b/packages/deepagent-code/src/panel/panel-convene-consumer.ts
index 1cda1ee8..0f0abecf 100644
--- a/packages/deepagent-code/src/panel/panel-convene-consumer.ts
+++ b/packages/deepagent-code/src/panel/panel-convene-consumer.ts
@@ -1,6 +1,6 @@
 export * as PanelConveneConsumer from "./panel-convene-consumer"
 
-import { Context, Effect, Layer, Stream, Schedule, Duration, Cause } from "effect"
+import { Context, Deferred, Effect, Layer, Stream, Schedule, Duration, Cause } from "effect"
 import { DeepAgentEventBus } from "@deepagent-code/core/deepagent/deepagent-event-bus"
 import { DeepAgentEvent } from "@deepagent-code/core/deepagent/deepagent-event"
 import { LMNEvents } from "@deepagent-code/core/deepagent/lmn-events"
@@ -255,9 +255,12 @@ export const layerWith = (options: LayerOptions) =>
         })
 
       if (runLoop) {
+        yield* bus.registerConsumerGroup(CONVENE_GROUP)
+        const ready = yield* Deferred.make<void>()
         yield* bus
           .subscribe({ group: CONVENE_GROUP })
           .pipe(
+            Stream.onStart(Deferred.succeed(ready, undefined)),
             Stream.runForEach((event) =>
               handle(event).pipe(
                 Effect.catchCause((cause) =>
@@ -268,6 +271,7 @@ export const layerWith = (options: LayerOptions) =>
             ),
             Effect.forkScoped,
           )
+        yield* Deferred.await(ready)
 
         yield* pumpRetries()
           .pipe(
diff --git a/packages/deepagent-code/src/provider/transform.ts b/packages/deepagent-code/src/provider/transform.ts
index 2b44e055..eaf857d4 100644
--- a/packages/deepagent-code/src/provider/transform.ts
+++ b/packages/deepagent-code/src/provider/transform.ts
@@ -838,14 +838,26 @@ export function variants(model: Provider.Model): Record<string, Record<string, a
     case "venice-ai-sdk-provider":
     // https://docs.venice.ai/overview/guides/reasoning-models#reasoning-effort
     case "@ai-sdk/openai-compatible": {
-      // For GPT-5.x versioned models routed through an openai-compatible endpoint, respect their
-      // extended effort tiers (xhigh from v5.2+) — same resolution logic as @ai-sdk/gateway.
-      // All other models on this adapter fall back to the base low/medium/high set.
       const apiId = model.api.id.toLowerCase()
+
+      // Anthropic models (Claude family) routed through an openai-compatible gateway — the gateway
+      // translates OpenAI-shaped `reasoningEffort` to Anthropic's native thinking API. Use the same
+      // adaptive effort set as the direct @ai-sdk/anthropic path (including xhigh for Opus 4.7+ and
+      // Fable 5+), expressed as `reasoningEffort` so the gateway can forward it correctly.
+      if (adaptiveEfforts && /\bclaude\b/i.test(apiId)) {
+        return Object.fromEntries(adaptiveEfforts.map((effort) => [effort, { reasoningEffort: effort }]))
+      }
+
+      // GPT-5.x versioned models support extended effort tiers (xhigh from v5.2+). Strip `none` and
+      // `minimal` — those are Responses-API-only tiers that openai-compatible endpoints do not
+      // implement, so exposing them would produce 400 errors on most third-party gateways.
       if (GPT5_FAMILY_RE.test(apiId)) {
-        const openaiCompatEfforts = openaiCompatibleReasoningEfforts(apiId)
+        const openaiCompatEfforts = openaiCompatibleReasoningEfforts(apiId).filter(
+          (e) => e !== "none" && e !== "minimal",
+        )
         return Object.fromEntries(openaiCompatEfforts.map((effort) => [effort, { reasoningEffort: effort }]))
       }
+
       const efforts = [...WIDELY_SUPPORTED_EFFORTS]
       if (apiId.includes("deepseek-v4")) {
         efforts.push("max")
diff --git a/packages/deepagent-code/src/server/routes/instance/httpapi/handlers/session.ts b/packages/deepagent-code/src/server/routes/instance/httpapi/handlers/session.ts
index 2baccb8e..66309b0b 100644
--- a/packages/deepagent-code/src/server/routes/instance/httpapi/handlers/session.ts
+++ b/packages/deepagent-code/src/server/routes/instance/httpapi/handlers/session.ts
@@ -433,7 +433,12 @@ export const sessionHandlers = HttpApiBuilder.group(InstanceHttpApi, "session",
       payload: typeof PromptPayload.Type
     }) {
       yield* requireSession(ctx.params.sessionID)
-      yield* promptSvc.prompt({ ...ctx.payload, sessionID: ctx.params.sessionID }).pipe(
+      // V4.1 §S1.2: mirror the synchronous `prompt` handler — route through promptOrSteer so a message
+      // sent while the session is mid-turn is admitted as a steer (absorbed at the next model-request
+      // boundary) instead of queuing as a new turn that starts only after the current one finishes.
+      // The turn result / steer ack is ignored here (we return 204 regardless); errors are published
+      // as session error events just like the old prompt() path.
+      yield* promptSvc.promptOrSteer({ ...ctx.payload, sessionID: ctx.params.sessionID }).pipe(
         Effect.catchCause((cause) =>
           Effect.gen(function* () {
             yield* Effect.logError("prompt_async failed").pipe(
diff --git a/packages/deepagent-code/src/session/event-dispatcher.ts b/packages/deepagent-code/src/session/event-dispatcher.ts
index 7089c0a5..e0a08700 100644
--- a/packages/deepagent-code/src/session/event-dispatcher.ts
+++ b/packages/deepagent-code/src/session/event-dispatcher.ts
@@ -496,6 +496,7 @@ export const layerWith = (options?: LayerOptions) =>
       // subscribe stream actually registering the consumer group, so no event published immediately
       // after the layer builds can slip through the startup window unrecorded (#2).
       if (runLoops) {
+        yield* bus.registerConsumerGroup(DISPATCH_GROUP)
         const ready = yield* Deferred.make<void>()
         yield* bus
           .subscribe({ group: DISPATCH_GROUP })
diff --git a/packages/deepagent-code/src/session/goal-tick-consumer.ts b/packages/deepagent-code/src/session/goal-tick-consumer.ts
index b508858e..063c0703 100644
--- a/packages/deepagent-code/src/session/goal-tick-consumer.ts
+++ b/packages/deepagent-code/src/session/goal-tick-consumer.ts
@@ -1,6 +1,6 @@
 export * as GoalTickConsumer from "./goal-tick-consumer"
 
-import { Context, Effect, Layer, Option, Stream, Schedule, Duration, Cause } from "effect"
+import { Context, Deferred, Effect, Layer, Option, Stream, Schedule, Duration, Cause } from "effect"
 import { DeepAgentEventBus } from "@deepagent-code/core/deepagent/deepagent-event-bus"
 import { DeepAgentEvent } from "@deepagent-code/core/deepagent/deepagent-event"
 import { LMNEvents } from "@deepagent-code/core/deepagent/lmn-events"
@@ -321,9 +321,12 @@ export const layerWith = (options: LayerOptions) =>
         })
 
       if (runLoop) {
+        yield* bus.registerConsumerGroup(TICK_GROUP, LMNEvents.GOAL_TICK_REQUESTED)
+        const ready = yield* Deferred.make<void>()
         yield* bus
           .subscribe({ type: LMNEvents.GOAL_TICK_REQUESTED, group: TICK_GROUP })
           .pipe(
+            Stream.onStart(Deferred.succeed(ready, undefined)),
             Stream.runForEach((event) =>
               handle(event).pipe(
                 Effect.catchCause((cause) =>
@@ -333,6 +336,7 @@ export const layerWith = (options: LayerOptions) =>
             ),
             Effect.forkScoped,
           )
+        yield* Deferred.await(ready)
 
         yield* pumpRetries()
           .pipe(
diff --git a/packages/deepagent-code/src/session/prompt.ts b/packages/deepagent-code/src/session/prompt.ts
index 79136e91..5403b577 100644
--- a/packages/deepagent-code/src/session/prompt.ts
+++ b/packages/deepagent-code/src/session/prompt.ts
@@ -111,7 +111,24 @@ IMPORTANT:
 - Complete all necessary research and tool calls BEFORE calling this tool
 - This tool provides your final answer - no further actions are taken after calling it`
 
-const STRUCTURED_OUTPUT_SYSTEM_PROMPT = `IMPORTANT: The user has requested structured output. You MUST use the StructuredOutput tool to provide your final response. Do NOT respond with plain text - you MUST call the StructuredOutput tool with your answer formatted according to the schema.`
+// P1: Build a schema-aware system prompt that injects the required field names so the model
+// knows the exact schema even during extended-thinking (xhigh) reasoning, without relying
+// solely on the tool definition which may not be visible during the thinking phase.
+function buildStructuredOutputSystemPrompt(schema: Record<string, any>): string {
+  const fields = extractSchemaTopLevelFields(schema)
+  const fieldHint =
+    fields.length > 0
+      ? `\nThe StructuredOutput tool requires these top-level fields: ${fields.join(", ")}. Use ONLY these exact field names.`
+      : ""
+  return `IMPORTANT: The user has requested structured output. You MUST use the StructuredOutput tool to provide your final response. Do NOT respond with plain text - you MUST call the StructuredOutput tool with your answer formatted according to the schema.${fieldHint}`
+}
+
+function extractSchemaTopLevelFields(schema: Record<string, any>): string[] {
+  if (!schema || typeof schema !== "object") return []
+  const props = schema.properties
+  if (!props || typeof props !== "object") return []
+  return Object.keys(props)
+}
 
 const log = Log.create({ service: "session.prompt" })
 const elog = EffectLogger.create({ service: "session.prompt" })
@@ -2086,6 +2103,12 @@ export const layer = Layer.effect(
         const slog = elog.with({ sessionID })
         let structured: unknown
         let step = 0
+        // P0: count StructuredOutput tool-call attempts that did NOT produce a valid structured
+        // result (schema validation rejected the arguments). When this reaches the format's
+        // retryCount ceiling we inject a corrective hint and exit — preventing the infinite loop
+        // that occurs when the model repeatedly guesses wrong field names (e.g. "summary" instead
+        // of "module" for ResearchResult) and the AI SDK silently rejects them before execute().
+        let structuredFailedAttempts = 0
         const session = yield* sessions.get(sessionID).pipe(Effect.orDie)
 
         // V3.8 App-A C2.5 (Stage 5): the Conversation Log writer. Constructed ONCE per run so its
@@ -2427,7 +2450,10 @@ export const layer = Layer.effect(
             ])
             const system = [...env, ...instructions, ...(skills ? [skills] : [])]
             const format = lastUser.format ?? { type: "text" as const }
-            if (format.type === "json_schema") system.push(STRUCTURED_OUTPUT_SYSTEM_PROMPT)
+            // P1: inject schema-aware prompt so the model knows the exact field names even
+            // during extended-thinking (xhigh) reasoning where the tool definition may not
+            // be immediately visible when the model starts generating its thinking tokens.
+            if (format.type === "json_schema") system.push(buildStructuredOutputSystemPrompt(format.schema))
             const result = yield* handle.process({
               user: lastUser,
               agent,
@@ -2460,6 +2486,62 @@ export const layer = Layer.effect(
               }
             }
 
+            // P0: StructuredOutput retry-cap. Only fires when:
+            //   1. format is json_schema (structured-output mode)
+            //   2. the model made tool-calls (finish === "tool-calls")
+            //   3. structured is still undefined (StructuredOutput was NOT successfully captured)
+            //   4. the current turn's parts actually contain a StructuredOutput call
+            //      (B1 fix: filter to ONLY StructuredOutput failures, not any tool call)
+            //
+            // When the model called StructuredOutput but AI SDK schema-validation rejected the
+            // arguments (wrong field names like "summary" instead of "module"), execute() never
+            // runs, onSuccess never fires, and structured stays undefined — causing an infinite
+            // loop. The retry-cap truncates this loop.
+            if (format.type === "json_schema" && handle.message.finish === "tool-calls") {
+              // Re-read the latest message parts to detect if StructuredOutput was attempted
+              // this step. We check the CURRENT assistant message's parts (by handle.message.id).
+              const latestMsgs = yield* MessageV2.filterCompactedEffect(sessionID).pipe(
+                Effect.provideService(Database.Service, database),
+              )
+              const currentAssistantMsg = latestMsgs.findLast(
+                (m) => m.info.role === "assistant" && m.info.id === handle.message.id,
+              )
+              const hadStructuredOutputCall = currentAssistantMsg?.parts.some(
+                (p) => p.type === "tool" && p.tool === "StructuredOutput",
+              ) ?? false
+
+              if (hadStructuredOutputCall) {
+                const retryMax = format.retryCount ?? 2
+                structuredFailedAttempts++
+                const fields = extractSchemaTopLevelFields(format.schema)
+                const fieldList = fields.length > 0 ? fields.join(", ") : "(see schema)"
+                if (structuredFailedAttempts >= retryMax) {
+                  handle.message.error = new SessionV1.StructuredOutputError({
+                    message: `StructuredOutput schema validation failed after ${structuredFailedAttempts} attempt(s). Required fields: ${fieldList}`,
+                    retries: structuredFailedAttempts,
+                  }).toObject()
+                  yield* sessions.updateMessage(handle.message)
+                  yield* slog.warn("structured-output retry cap reached", {
+                    attempts: structuredFailedAttempts,
+                    retryMax,
+                    fields: fieldList,
+                  })
+                  return "break" as const
+                }
+                // B2 fix: inject via injectTailReminder (user-side synthetic message) so the
+                // correction text appears as a user instruction in the next model context —
+                // not as assistant output (which the model treats with lower compliance).
+                if (fields.length > 0) {
+                  yield* injectTailReminder(
+                    sessionID,
+                    `[structured-output correction] Your StructuredOutput call did not match the required schema. Required top-level fields: ${fieldList}. Please call StructuredOutput again using EXACTLY these field names.`,
+                    lastUser.model,
+                    lastUser.agent,
+                  )
+                }
+              }
+            }
+
             if (result === "stop") return "break" as const
             if (result === "compact") {
               // V4.0.1 P0 — a turn-internal hard compaction (the provider signalled overflow mid-stream).
@@ -2583,6 +2665,12 @@ export const layer = Layer.effect(
           sessionID: input.sessionID,
           text,
           delivery: "goal_steer",
+          // §S1.2 ID bridge: forward the client-supplied messageID so the steer row carries the same
+          // id as the frontend's optimistic message — prevents a duplicate entry when drainSteers
+          // materialises the steer into V1 history. PromptInput.messageID is a different Schema brand
+          // (MessageID vs SessionMessage.ID) but both are ascending-string ids at runtime; the cast is
+          // safe because sendFollowupDraft always mints via Identifier.ascending().
+          messageID: input.messageID as unknown as SessionMessage.ID | undefined,
         })
         // V4.1 governance audit — this is the REAL user goal-steer path (the ingress every busy-goal
         // steer flows through). Record the human intervention into the goal's Document Graph alongside
@@ -2598,13 +2686,17 @@ export const layer = Layer.effect(
         const message = yield* prompt(input)
         return { kind: "turn" as const, message }
       }
-      // Let steer() mint a fresh ascending SessionMessage.ID (tail-sorting, §S1.1 Check 3). We do NOT
-      // forward input.messageID: it is a PromptInput MessageID (a different brand) and a client-supplied id
-      // could be non-ascending and insert mid-history — breaking order + cache.
+      // §S1.2 ID bridge: forward the client-supplied messageID so the steer row carries the same id as
+      // the frontend's optimistic message — prevents a duplicate entry when drainSteers materialises
+      // the steer into V1 history. PromptInput.messageID is a different Schema brand (MessageID vs
+      // SessionMessage.ID) but both are ascending-string ids at runtime; the cast is safe because
+      // sendFollowupDraft always mints via Identifier.ascending(). steer() will still generate a fresh
+      // ascending id when messageID is omitted (e.g. non-async callers that don't supply one).
       const admitted = yield* steer({
         sessionID: input.sessionID,
         text: promptInputText(input.parts),
         delivery: "steer",
+        messageID: input.messageID as unknown as SessionMessage.ID | undefined,
       })
       // Race guard (see header): a pure-drain turn absorbs a steer stranded by the isBusy→admit window.
       yield* loop({ sessionID: input.sessionID, drainFirst: true }).pipe(Effect.ignore, Effect.forkIn(scope))
@@ -2959,6 +3051,9 @@ const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === "object" && value !== null && !Array.isArray(value)
 
 /** @internal Exported for testing */
+/** @internal Exported for testing */
+export { buildStructuredOutputSystemPrompt, extractSchemaTopLevelFields }
+
 export function createStructuredOutputTool(input: {
   schema: Record<string, any>
   onSuccess: (output: unknown) => void
diff --git a/packages/deepagent-code/src/session/supervisor-notifier.ts b/packages/deepagent-code/src/session/supervisor-notifier.ts
index c0a616a3..a1a4bf58 100644
--- a/packages/deepagent-code/src/session/supervisor-notifier.ts
+++ b/packages/deepagent-code/src/session/supervisor-notifier.ts
@@ -1,6 +1,6 @@
 export * as SupervisorNotifier from "./supervisor-notifier"
 
-import { Context, Effect, Layer, Stream, Schedule, Duration, Cause } from "effect"
+import { Context, Deferred, Effect, Layer, Stream, Schedule, Duration, Cause } from "effect"
 import { and, eq, isNull, inArray } from "drizzle-orm"
 import { Database } from "@deepagent-code/core/database/database"
 import { DeepAgentEventBus } from "@deepagent-code/core/deepagent/deepagent-event-bus"
@@ -260,9 +260,12 @@ export const layerWith = (options?: LayerOptions) =>
         })
 
       if (runLoop) {
+        yield* bus.registerConsumerGroup(NOTIFY_GROUP)
+        const ready = yield* Deferred.make<void>()
         yield* bus
           .subscribe({ group: NOTIFY_GROUP })
           .pipe(
+            Stream.onStart(Deferred.succeed(ready, undefined)),
             Stream.runForEach((event) =>
               handle(event).pipe(
                 Effect.asVoid,
@@ -273,6 +276,7 @@ export const layerWith = (options?: LayerOptions) =>
             ),
             Effect.forkScoped,
           )
+        yield* Deferred.await(ready)
 
         yield* pumpRetries()
           .pipe(
diff --git a/packages/deepagent-code/src/session/v4-event-runtime.ts b/packages/deepagent-code/src/session/v4-event-runtime.ts
index 5bebe42a..6f4281ac 100644
--- a/packages/deepagent-code/src/session/v4-event-runtime.ts
+++ b/packages/deepagent-code/src/session/v4-event-runtime.ts
@@ -1,6 +1,7 @@
 export * as V4EventRuntime from "./v4-event-runtime"
 
 import { Cause, Duration, Effect, Layer, Schedule } from "effect"
+import { LMNEvents } from "@deepagent-code/core/deepagent/lmn-events"
 import { DeepAgentEventBus } from "@deepagent-code/core/deepagent/deepagent-event-bus"
 import { ApprovalQueue } from "@deepagent-code/core/deepagent/approval-queue"
 import { WorkspaceConfig } from "@deepagent-code/core/deepagent/workspace-config"
@@ -21,21 +22,21 @@ import { InstanceRef, WorkspaceRef } from "@/effect/instance-ref"
 import { WorkspaceV2 } from "@deepagent-code/core/workspace"
 import { RuntimeFlags } from "@/effect/runtime-flags"
 import { MultiAgentRuntime } from "./multi-agent-runtime"
-import { EventDispatcher } from "./event-dispatcher"
+import { EventDispatcher, DISPATCH_GROUP } from "./event-dispatcher"
 import type { SubagentTurnRunner, SubagentTurnResult } from "./goal-loop-wiring"
 import { MessageID } from "./schema"
 import { SessionCompletedPublisher } from "./session-completed-publisher"
-import { EventDrivenArchiver } from "@/wiki/event-driven-archiver"
-import { PanelConveneConsumer } from "@/panel/panel-convene-consumer"
+import { EventDrivenArchiver, ARCHIVE_GROUP } from "@/wiki/event-driven-archiver"
+import { PanelConveneConsumer, CONVENE_GROUP } from "@/panel/panel-convene-consumer"
 import { consultPanel } from "@/panel/consult"
 import type { PanelTurnRunner } from "@/panel/panelist-runner"
 import { makeTaskSubagentRunner } from "./goal-loop-wiring"
 // §B2/§E4 (P2.8) — proactive push stack.
 import { AgentPush } from "./agent-push"
 import { DigestBuilder } from "./digest-builder"
-import { SupervisorNotifier } from "./supervisor-notifier"
+import { SupervisorNotifier, NOTIFY_GROUP } from "./supervisor-notifier"
 // V4.1 §N — the event-driven goal-tick consumer + its production cold-reconstruction port.
-import { GoalTickConsumer } from "./goal-tick-consumer"
+import { GoalTickConsumer, TICK_GROUP } from "./goal-tick-consumer"
 import { GoalTickPort } from "./goal-tick-port"
 import { goalStoreRoot } from "./goal-manager"
 import { SessionRevert } from "./revert"
@@ -457,6 +458,22 @@ const anyV4DaemonEnabled = (flags: RuntimeFlags.Info): boolean =>
   flags.v4AgentPushEnabled ||
   flags.v4EventDrivenArchive
 
+// Register the durable delivery policy before any V4 publisher can emit. `Layer.mergeAll` starts
+// components concurrently, so relying on each consumer's live subscribe stream loses first-start events.
+// Individual consumers repeat this idempotently for standalone use; this layer establishes the runtime
+// producer-after-registration boundary. Disabled groups are deliberately absent and accrue no backlog.
+const consumerRegistrationLayer = Layer.effectDiscard(
+  Effect.gen(function* () {
+    const flags = yield* RuntimeFlags.Service
+    const bus = yield* DeepAgentEventBus.Service
+    if (anyV4DaemonEnabled(flags)) yield* bus.registerConsumerGroup(DISPATCH_GROUP)
+    if (flags.v4MultiAgentRuntime) yield* bus.registerConsumerGroup(TICK_GROUP, LMNEvents.GOAL_TICK_REQUESTED)
+    if (flags.v4PanelAutoConvene) yield* bus.registerConsumerGroup(CONVENE_GROUP)
+    if (flags.v4EventDrivenArchive || flags.v4MultiAgentRuntime) yield* bus.registerConsumerGroup(ARCHIVE_GROUP)
+    if (flags.v4AgentPushEnabled) yield* bus.registerConsumerGroup(NOTIFY_GROUP)
+  }),
+)
+
 // The EventDispatcher layer whose DispatchPort is the live MultiAgentRuntime. Its subscribe/tick/retry
 // daemons run only when a V4 daemon is enabled (else runLoops:false ⇒ built but dormant). The dispatcher
 // additionally flag-checks v4MultiAgentRuntime per event before dispatching.
@@ -776,6 +793,7 @@ export const layer = Layer.mergeAll(
   // Shares the ONE DeepAgentEventBus + ApprovalQueue + session stack with the rest of the runtime.
   goalTickConsumerLayer,
 ).pipe(
+  Layer.provideMerge(consumerRegistrationLayer),
   Layer.provideMerge(runtimeLayer),
 )
 
diff --git a/packages/deepagent-code/src/tool/registry.ts b/packages/deepagent-code/src/tool/registry.ts
index 1998e480..7e22104b 100644
--- a/packages/deepagent-code/src/tool/registry.ts
+++ b/packages/deepagent-code/src/tool/registry.ts
@@ -9,6 +9,7 @@ import { GrepTool } from "./grep"
 import { ReadTool } from "./read"
 import { TaskTool } from "./task"
 import { TaskStatusTool } from "./task_status"
+import { TaskReadTool } from "./task_read"
 import { DismissValidationTool } from "./dismiss_validation"
 import { Database } from "@deepagent-code/core/database/database"
 import { WebFetchTool } from "./webfetch"
@@ -129,6 +130,7 @@ export const layer: Layer.Layer<
     const invalid = yield* InvalidTool
     const task = yield* TaskTool
     const taskstatus = yield* TaskStatusTool
+    const taskread = yield* TaskReadTool
     const dismissvalidation = yield* DismissValidationTool
     const read = yield* ReadTool
     const question = yield* QuestionTool
@@ -259,6 +261,7 @@ export const layer: Layer.Layer<
           write: Tool.init(writetool),
           task: Tool.init(task),
           task_status: Tool.init(taskstatus),
+          task_read: Tool.init(taskread),
           dismiss_validation: Tool.init(dismissvalidation),
           fetch: Tool.init(webfetch),
           search: Tool.init(websearch),
@@ -287,6 +290,7 @@ export const layer: Layer.Layer<
             tool.write,
             tool.task,
             tool.task_status,
+            tool.task_read,
             tool.dismiss_validation,
             tool.fetch,
             tool.search,
diff --git a/packages/deepagent-code/src/tool/task.ts b/packages/deepagent-code/src/tool/task.ts
index 4b4cd438..17e018e5 100644
--- a/packages/deepagent-code/src/tool/task.ts
+++ b/packages/deepagent-code/src/tool/task.ts
@@ -174,9 +174,10 @@ interface AttemptBundle {
   readonly worktree: Worktree.Interface | undefined
   readonly nextSession: Session.Info
   readonly metadata: AttemptMetadata
-  readonly markFinished: (state: "completed" | "error" | "cancelled") => Effect.Effect<void, unknown>
+  readonly markFinished: (state: "completed" | "error" | "cancelled" | "interrupted", reason?: "human" | "parent_interrupted" | "timeout" | "takeover" | "runtime_error") => Effect.Effect<void, unknown>
   readonly inject: (state: "completed" | "error", text: string, takeovers: number) => Effect.Effect<unknown, unknown>
-  readonly mergeWorktree: () => Effect.Effect<void, unknown>
+  readonly automaticWriteIsolation: boolean
+  readonly mergeWorktree: () => Effect.Effect<boolean, unknown>
   readonly teardownWorktree: (force: boolean) => Effect.Effect<unknown, unknown>
 }
 
@@ -391,7 +392,8 @@ export const TaskTool = Tool.define(
           })
 
           const markFinished = Effect.fn("TaskTool.markSubagentFinished")(function* (
-            state: "completed" | "error" | "cancelled",
+            state: "completed" | "error" | "cancelled" | "interrupted",
+            reason?: "human" | "parent_interrupted" | "timeout" | "takeover" | "runtime_error",
           ) {
             const current = yield* sessions.get(a.nextSession.id).pipe(Effect.orDie)
             yield* sessions
@@ -401,7 +403,9 @@ export const TaskTool = Tool.define(
                   ...(current.metadata ?? {}),
                   deepagent: {
                     ...((current.metadata?.["deepagent"] as Record<string, unknown> | undefined) ?? {}),
-                    subagent: { finished: true, state, at: Date.now() },
+                    // §4.3 SubagentRunMetadata: state is the durable authority for terminal state.
+                    // Compat: old data using `finished: true` with state is still readable unchanged.
+                    subagent: { finished: true, state, at: Date.now(), ...(reason ? { reason } : {}) },
                   },
                 },
               })
@@ -466,8 +470,9 @@ export const TaskTool = Tool.define(
           // worktree for recovery; teardownWorktree(false) is then called by the caller to keep it.
           //
           // We resolve Git.Service here (at bundle-build time inside startAttempt) so that
-          // mergeWorktree itself can be typed as () => Effect<void, unknown> (no service requirements):
-          // the service is captured in the closure, not re-required at call time.
+          // mergeWorktree itself can be typed without service requirements: the service is captured
+          // in the closure. `true` reports a successful automatic merge, whose worker may be removed.
+          // `false` means no automatic merge was applicable and therefore must keep fail-closed cleanup.
           const automaticWriteIsolation = params.isolation !== "worktree" && !!a.worktreeInfo
           const parentDir = parent.directory
           const gitOpt = yield* Effect.serviceOption(Git.Service)
@@ -476,10 +481,10 @@ export const TaskTool = Tool.define(
               ? yield* gitOpt.value.resolveRef(parentDir).pipe(Effect.orElseSucceed(() => undefined))
               : undefined
           const mergeWorktree = Effect.fn("TaskTool.mergeWorktree")(function* () {
-            if (!a.worktreeInfo || !automaticWriteIsolation || !parentDir || Option.isNone(gitOpt)) return
+            if (!a.worktreeInfo || !automaticWriteIsolation || !parentDir || Option.isNone(gitOpt)) return false
             const git = gitOpt.value
             const workerBranch = a.worktreeInfo.branch
-            if (!workerBranch) return // detached HEAD on worker — nothing to merge
+            if (!workerBranch) return false // detached HEAD on worker — nothing to merge
             const currentParentHead = yield* git.resolveRef(parentDir).pipe(Effect.orElseSucceed(() => undefined))
             if (currentParentHead !== parentBaselineHead) {
               // Parent advanced — preserve worker for human resolution; caller treats this as merge failure.
@@ -492,7 +497,7 @@ export const TaskTool = Tool.define(
               )
             }
             const result = yield* git.mergeInto(parentDir, workerBranch)
-            if (result.type === "merged") return
+            if (result.type === "merged") return true
             // On conflict or failure: abort merge state so parent checkout is usable, then re-throw
             // so the caller knows to preserve the worker worktree.
             yield* git.abortMerge(parentDir).pipe(Effect.ignore)
@@ -513,6 +518,7 @@ export const TaskTool = Tool.define(
             worktree: a.worktree,
             nextSession: a.nextSession,
             metadata,
+            automaticWriteIsolation,
             markFinished,
             inject,
             mergeWorktree,
@@ -590,7 +596,6 @@ export const TaskTool = Tool.define(
             if (outcome.kind === "promoted") return backgroundResult(b)
             if (outcome.kind === "completed") {
               const merged = yield* b.mergeWorktree().pipe(
-                Effect.as(true),
                 Effect.catchCause((cause) =>
                   Effect.gen(function* () {
                     const diagnostic = Cause.squash(cause)
@@ -601,9 +606,9 @@ export const TaskTool = Tool.define(
                   }),
                 ),
               )
-              if (!merged) return yield* Effect.fail(new Error("Worktree merge-back failed"))
+              if (!merged && b.automaticWriteIsolation) return yield* Effect.fail(new Error("Worktree merge-back failed"))
               yield* b.markFinished("completed")
-              yield* b.teardownWorktree(true)
+              yield* b.teardownWorktree(merged)
               return {
                 title: params.description,
                 metadata: b.metadata,
@@ -616,9 +621,18 @@ export const TaskTool = Tool.define(
               }
             }
             if (outcome.kind === "cancelled") {
-              yield* b.markFinished("cancelled")
+              // §4.3/4.6: "cancelled" from the abort signal means human interrupted the task.
+              // Write "interrupted" (not "cancelled") so parent agent and supervision UI can
+              // distinguish voluntary human stop with preserved work from a runtime failure.
+              // Do NOT force-remove the worktree — partial work may be worth recovering.
+              yield* b.markFinished("interrupted", "human")
               yield* b.teardownWorktree(false)
-              return yield* Effect.fail(new Error("Task cancelled"))
+              return yield* Effect.fail(
+                new Error(
+                  `Task interrupted by the user. Partial work is preserved in subagent session ${b.nextSession.id}. ` +
+                    `Call task_read({ task_id: "${b.nextSession.id}" }) before retrying or duplicating the task.`,
+                ),
+              )
             }
             if (takeovers >= takeoverLimit) {
               yield* background.cancel(b.nextSession.id).pipe(Effect.ignore)
@@ -651,7 +665,6 @@ export const TaskTool = Tool.define(
             const status = waited.info?.status
             if (!waited.timedOut && status === "completed") {
               const merged = yield* b.mergeWorktree().pipe(
-                Effect.as(true),
                 Effect.catchCause((cause) =>
                   Effect.gen(function* () {
                     const diagnostic = Cause.squash(cause)
@@ -662,9 +675,9 @@ export const TaskTool = Tool.define(
                   }),
                 ),
               )
-              if (!merged) return
+              if (!merged && b.automaticWriteIsolation) return
               yield* b.markFinished("completed")
-              yield* b.teardownWorktree(true)
+              yield* b.teardownWorktree(merged)
               yield* b.inject("completed", waited.info?.output ?? "", takeovers)
               return
             }
@@ -882,6 +895,22 @@ export const TaskTool = Tool.define(
         if (resolvedOutputSchema) {
           const structured = result.info.role === "assistant" ? result.info.structured : undefined
           if (structured !== undefined) return JSON.stringify(structured)
+          // B3 fix: when the retry cap fired, the assistant message carries a StructuredOutputError.
+          // Silently returning "" here would make the parent agent see an empty success result and
+          // lose all signal that the subagent failed to produce structured output. Surface the error
+          // explicitly so the task tool's error path propagates it correctly to the parent.
+          const msgError = result.info.role === "assistant" ? result.info.error : undefined
+          if (msgError && SessionV1.StructuredOutputError.isInstance(msgError)) {
+            return yield* Effect.fail(
+              new Error(
+                // U1: include the child session ID so the parent agent can recover partial work via
+                // task_read({ task_id: nextSession.id }) before retrying or duplicating the task.
+                `StructuredOutput failed (${msgError.data.retries} attempt(s)): ${msgError.data.message}. ` +
+                  `Partial research is preserved in subagent session ${nextSession.id}. ` +
+                  `Call task_read({ task_id: "${nextSession.id}" }) to recover completed work before retrying.`,
+              ),
+            )
+          }
         }
         return result.parts.findLast((item) => item.type === "text")?.text ?? ""
       })
@@ -926,7 +955,8 @@ export const TaskTool = Tool.define(
       // only flips the UI to "已完成" and disables the composer; it touches no message/part data.
       // Read-merge because setMetadata replaces the whole metadata object.
       const markFinished = Effect.fn("TaskTool.markSubagentFinished")(function* (
-        state: "completed" | "error" | "cancelled",
+        state: "completed" | "error" | "cancelled" | "interrupted",
+        reason?: "human" | "parent_interrupted" | "timeout" | "takeover" | "runtime_error",
       ) {
         // Resume (`params.task_id`) reuses an existing session; a fresh finish marker is still correct
         // (the reused session just completed another turn), so no special-casing is needed.
@@ -938,7 +968,8 @@ export const TaskTool = Tool.define(
               ...(current.metadata ?? {}),
               deepagent: {
                 ...((current.metadata?.["deepagent"] as Record<string, unknown> | undefined) ?? {}),
-                subagent: { finished: true, state, at: Date.now() },
+                // §4.3: state is the durable terminal-state authority; reason narrows the cause.
+                subagent: { finished: true, state, at: Date.now(), ...(reason ? { reason } : {}) },
               },
             },
           })
@@ -1039,8 +1070,13 @@ export const TaskTool = Tool.define(
               return yield* Effect.fail(new Error(result.error ?? "Task failed"))
             }
             if (result?.status === "cancelled") {
-              yield* markFinished("cancelled")
-              return yield* Effect.fail(new Error("Task cancelled"))
+              yield* markFinished("interrupted", "human")
+              return yield* Effect.fail(
+                new Error(
+                  `Task interrupted by the user. Partial work is preserved in subagent session ${nextSession.id}. ` +
+                    `Call task_read({ task_id: "${nextSession.id}" }) before retrying or duplicating the task.`,
+                ),
+              )
             }
             yield* markFinished("completed")
             return {
diff --git a/packages/deepagent-code/src/tool/task_read.ts b/packages/deepagent-code/src/tool/task_read.ts
new file mode 100644
index 00000000..58f2c4f3
--- /dev/null
+++ b/packages/deepagent-code/src/tool/task_read.ts
@@ -0,0 +1,182 @@
+import * as Tool from "./tool"
+import { Session } from "@/session/session"
+import { SessionV1 } from "@deepagent-code/core/v1/session"
+import { Effect, Schema } from "effect"
+import type { SessionID } from "@/session/schema"
+
+const id = "task_read"
+
+const DESCRIPTION = [
+  "Read the transcript of a subagent task you dispatched via the task tool.",
+  "Parameters: task_id (the session ID from task_status output), limit (default 20, max 100), before (message ID cursor for pagination).",
+  "Returns up to `limit` messages from the subagent's conversation, newest-first.",
+  "Use this to recover partial work when a subagent was interrupted or failed to produce structured output.",
+  "IMPORTANT: Only reads sessions you directly spawned (child sessions of the current session).",
+  "Never returns hidden reasoning content.",
+].join(" ")
+
+const Parameters = Schema.Struct({
+  task_id: Schema.String.annotate({ description: "The subagent session ID (from task_status output)" }),
+  limit: Schema.optional(Schema.Number).annotate({
+    description: "Max messages to return (default 20, max 100)",
+  }),
+  before: Schema.optional(Schema.String).annotate({
+    description: "Message ID cursor for pagination (from the 'before' hint in a previous call)",
+  }),
+})
+
+const MAX_LIMIT = 100
+const DEFAULT_LIMIT = 20
+
+/** Render a single tool part into the transcript. */
+function renderToolPart(part: SessionV1.ToolPart): string {
+  const state = part.state.status
+  const name = part.tool ?? "unknown"
+  if (state === "running" || state === "pending") {
+    return `  <tool name="${name}" state="${state}"/>`
+  }
+  if (state === "error") {
+    const err = part.state.error ?? "error"
+    return `  <tool name="${name}" state="error">${truncate(String(err), 200)}</tool>`
+  }
+  if (state === "completed") {
+    const output = part.state.output ?? part.state.metadata?.output ?? ""
+    return `  <tool name="${name}" state="completed">${truncate(String(output), 400)}</tool>`
+  }
+  return `  <tool name="${name}" state="${state}"/>`
+}
+
+function renderTextPart(part: SessionV1.TextPart): string | undefined {
+  // Skip synthetic parts (system injections) and ignored parts from the transcript.
+  if (part.synthetic || part.ignored) return undefined
+  const text = part.text?.trim()
+  if (!text) return undefined
+  return `  <text>${truncate(text, 600)}</text>`
+}
+
+function truncate(text: string, maxLen: number): string {
+  if (text.length <= maxLen) return text
+  return text.slice(0, maxLen - 1) + "…"
+}
+
+/**
+ * §4.5: task_read — parent-session-constrained child transcript reader.
+ *
+ * Security boundary: ONLY reads sessions whose parentID equals the calling session's ID.
+ * This prevents using a known session ID to read arbitrary other sessions.
+ */
+export const TaskReadTool = Tool.define(
+  id,
+  Effect.gen(function* () {
+    const sessions = yield* Session.Service
+
+    const run = Effect.fn("TaskReadTool.execute")(function* (
+      params: Schema.Schema.Type<typeof Parameters>,
+      ctx: Tool.Context,
+    ) {
+      const childSessionID = params.task_id as SessionID
+      const limit = Math.min(params.limit ?? DEFAULT_LIMIT, MAX_LIMIT)
+
+      // §4.5 security boundary: verify the requested session is a direct child of the calling session.
+      const child = yield* sessions.get(childSessionID).pipe(
+        Effect.catchCause(() =>
+          Effect.fail(new Error(`task_read: session not found: ${params.task_id}`)),
+        ),
+      )
+      if (child.parentID !== ctx.sessionID) {
+        return yield* Effect.fail(
+          new Error(
+            `task_read: session ${params.task_id} is not a direct subagent of the current session. ` +
+              `Only direct subagent sessions may be read.`,
+          ),
+        )
+      }
+
+      // Read messages — Session.messages returns them oldest-first, we reverse for newest-first cursor.
+      const allMessages = yield* sessions
+        .messages({ sessionID: childSessionID, limit: MAX_LIMIT + 1 })
+        .pipe(Effect.catchCause(() => Effect.succeed([] as SessionV1.WithParts[])))
+
+      // Apply `before` cursor (message ID boundary for pagination).
+      const beforeID = params.before
+      const filteredMessages = beforeID
+        ? allMessages.filter((m) => m.info.id < beforeID)
+        : allMessages
+
+      // Take newest `limit` messages.
+      const page = filteredMessages.slice(-limit)
+      const hasMore = filteredMessages.length > limit
+      const nextCursor = page[0]?.info.id
+
+      // Read durable state from metadata.
+      const deepagent = child.metadata?.["deepagent"] as Record<string, unknown> | undefined
+      const subagent = deepagent?.["subagent"] as Record<string, unknown> | undefined
+      const durableState = subagent
+        ? (subagent["state"] as string | undefined) ??
+          (subagent["finished"] === true ? "completed" : "unknown")
+        : "running"
+
+      // Format transcript lines.
+      const lines: string[] = []
+      for (const msg of page) {
+        const role = msg.info.role
+        if (role === "user") {
+          const textParts = msg.parts
+            .filter((p): p is SessionV1.TextPart => p.type === "text" && !p.synthetic && !p.ignored)
+            .map((p) => p.text?.trim())
+            .filter(Boolean)
+          if (textParts.length > 0) {
+            lines.push(`<message role="user">${truncate(textParts.join(" "), 600)}</message>`)
+          }
+        } else if (role === "assistant") {
+          for (const part of msg.parts) {
+            if (part.type === "text") {
+              const rendered = renderTextPart(part)
+              if (rendered) lines.push(`<message role="assistant">${truncate(part.text?.trim() ?? "", 600)}</message>`)
+            } else if (part.type === "tool") {
+              lines.push(renderToolPart(part))
+            }
+          }
+          // Mark interrupted/error assistant messages.
+          const msgInfo = msg.info
+          if (msgInfo.role === "assistant" && msgInfo.error) {
+            const name = msgInfo.error.name ?? "error"
+            const data = msgInfo.error.data
+            const msg_text =
+              name === "StructuredOutputError" && data
+                ? `StructuredOutput failed after ${(data as Record<string, unknown>)["retries"] ?? "?"} attempt(s)`
+                : String(name)
+            lines.push(`  <interruption>${truncate(msg_text, 200)}</interruption>`)
+          }
+        }
+      }
+
+      // Pagination hint at the end.
+      const moreHint = hasMore && nextCursor ? ` more="true" before="${nextCursor}"` : ""
+      const transcript = [
+        `<task_transcript id="${childSessionID}" state="${durableState}"${moreHint}>`,
+        ...lines.map((l) => `  ${l}`),
+        `</task_transcript>`,
+      ].join("\n")
+
+      // Pagination instruction when truncated.
+      const paginationHint =
+        hasMore && nextCursor
+          ? `\n[Truncated. Older messages available. Call task_read({ task_id: "${childSessionID}", before: "${nextCursor}" }) for the previous page.]`
+          : ""
+
+      return {
+        title: `Task transcript: ${child.title ?? childSessionID}`,
+        metadata: { sessionID: childSessionID, state: durableState, messageCount: page.length, hasMore },
+        output: transcript + paginationHint,
+      }
+    })
+
+    return {
+      description: DESCRIPTION,
+      parameters: Parameters,
+      execute: (params: Schema.Schema.Type<typeof Parameters>, ctx: Tool.Context) =>
+        run(params, ctx).pipe(Effect.catchCause((cause) => Effect.die(cause))),
+    }
+  }),
+)
diff --git a/packages/deepagent-code/src/tool/task_status.ts b/packages/deepagent-code/src/tool/task_status.ts
index 4f282846..5d8990f5 100644
--- a/packages/deepagent-code/src/tool/task_status.ts
+++ b/packages/deepagent-code/src/tool/task_status.ts
@@ -1,13 +1,17 @@
 import * as Tool from "./tool"
 import { BackgroundJob } from "@/background/job"
+import { Session } from "@/session/session"
 import { Effect, Schema } from "effect"
+import type { SessionID } from "@/session/schema"
 
 const id = "task_status"
 
 const DESCRIPTION = [
   "List the subagent tasks this session has dispatched (via the task tool), oldest first.",
-  "For each: status (running/completed/error/cancelled), agent type, title, elapsed time, and session/job id.",
-  "Use it to check on a subagent that has not reported back before deciding to wait, retry, or take over.",
+  "For each: session ID, status (running/completed/error/interrupted/cancelled), agent type, title, elapsed time.",
+  "Uses durable child-session records as the authoritative source so results survive process restarts.",
+  "Live elapsed time is overlaid from the current process's BackgroundJob registry when available.",
+  "Use it to check on a subagent before deciding to wait, retry, take over, or call task_read to recover partial work.",
   "Read-only: it never starts, cancels, or modifies tasks.",
 ].join(" ")
 
@@ -21,37 +25,100 @@ function formatDuration(ms: number) {
   return `${minutes}m${seconds % 60}s`
 }
 
+function formatAge(ts: number): string {
+  return formatDuration(Date.now() - ts)
+}
+
 /**
- * v4.0.4 块1 (1c): model-callable, READ-ONLY view over the BackgroundJob registry so the parent
- * agent can check on subagents it dispatched (a hung subagent that never reports back is otherwise
- * invisible). Jobs are filtered to the CURRENT session via metadata.parentSessionId — other
- * sessions' tasks are never exposed. No timeout/takeover behavior is gated here; listing works
- * regardless of flags.
+ * §4.4: durable task_status — two-layer merge.
+ *
+ * Layer 1 (authoritative): Session.children(parentID) — durable DB records. Survives process
+ * restarts and gives the canonical terminal state written by task.ts markFinished.
+ *
+ * Layer 2 (advisory): BackgroundJob.list() — current-process live jobs. Overlays elapsed time
+ * and "running" status for jobs that haven't written their terminal marker yet.
+ *
+ * Backward compat: old child sessions with no subagent metadata are shown as "unknown" state,
+ * not silently omitted or shown as "running" (which would be misleading).
  */
 export const TaskStatusTool = Tool.define(
   id,
   Effect.gen(function* () {
     const background = yield* BackgroundJob.Service
+    const sessions = yield* Session.Service
 
     const run = Effect.fn("TaskStatusTool.execute")(function* (
       _params: Schema.Schema.Type<typeof Parameters>,
       ctx: Tool.Context,
     ) {
-      const jobs = (yield* background.list()).filter((job) => job.metadata?.parentSessionId === ctx.sessionID)
       const now = Date.now()
-      const lines = jobs.map((job) => {
-        const duration = formatDuration((job.completed_at ?? now) - job.started_at)
-        const title = job.title ? ` "${job.title}"` : ""
-        // Prefer the real subagent type (researcher/reviewer/…) recorded in metadata; fall back to the
-        // BackgroundJob type only if a job predates the metadata (always "task" there, so uninformative).
-        const rawType = job.metadata?.subagentType
-        const agentType = typeof rawType === "string" && rawType.length > 0 ? rawType : job.type
-        return `- [${job.status}] ${agentType}${title} (${duration}) id=${job.id}`
+
+      // Layer 1: durable child sessions from DB.
+      const children = yield* sessions.children(ctx.sessionID as SessionID).pipe(
+        Effect.catchCause(() => Effect.succeed([] as Session.Info[])),
+      )
+
+      // Layer 2: live BackgroundJob overlay (process-local, advisory).
+      const liveJobs = yield* background.list().pipe(
+        Effect.map((jobs) => {
+          const m = new Map<string, (typeof jobs)[number]>()
+          for (const job of jobs) {
+            if (job.metadata?.parentSessionId === ctx.sessionID) {
+              const sessionId = job.metadata?.sessionId ?? job.id
+              if (typeof sessionId === "string") m.set(sessionId, job)
+            }
+          }
+          return m
+        }),
+        Effect.catchCause(() => Effect.succeed(new Map<string, never>())),
+      )
+
+      const lines = children.map((child) => {
+        const deepagent = child.metadata?.["deepagent"] as Record<string, unknown> | undefined
+        const subagent = deepagent?.["subagent"] as Record<string, unknown> | undefined
+        const liveJob = liveJobs.get(child.id)
+
+        // Determine durable state from metadata (written by markFinished).
+        const durableState = subagent
+          ? (subagent["state"] as string | undefined) ??
+            // compat: old rows used `finished: true` without state field
+            (subagent["finished"] === true ? "completed" : "unknown")
+          : "unknown"
+
+        // If a live job is running in the current process, override to "running".
+        const state =
+          liveJob && liveJob.status === "running" ? "running" : durableState
+
+        // Prefer live job elapsed time; fall back to metadata timestamp.
+        const elapsedMs =
+          liveJob && state === "running"
+            ? now - liveJob.started_at
+            : subagent?.["at"]
+              ? now - (subagent["at"] as number)
+              : undefined
+        const duration = elapsedMs !== undefined ? ` (${formatDuration(elapsedMs)})` : ""
+
+        // Agent type and title from session metadata or BackgroundJob.
+        const rawType = subagent?.["subagentType"] ?? liveJob?.metadata?.subagentType ?? child.agent ?? "task"
+        const agentType = typeof rawType === "string" && rawType.length > 0 ? rawType : "task"
+        const title = child.title && !child.title.startsWith("New Conversation") ? ` "${child.title}"` : ""
+
+        // §4.6 recovery hint for interrupted tasks.
+        const recoverHint =
+          state === "interrupted"
+            ? ` [partial work preserved — call task_read({ task_id: "${child.id}" }) to recover]`
+            : state === "error"
+              ? ` [call task_read({ task_id: "${child.id}" }) to inspect partial work]`
+              : ""
+
+        return `- [${state}] ${agentType}${title}${duration} id=${child.id}${recoverHint}`
       })
+
       const output =
         lines.length === 0
           ? "No subagent tasks dispatched by this session."
           : [`${lines.length} subagent task(s) dispatched by this session:`, ...lines].join("\n")
+
       return {
         title: "Subagent task status",
         metadata: { count: lines.length },
diff --git a/packages/deepagent-code/src/wiki/event-driven-archiver.ts b/packages/deepagent-code/src/wiki/event-driven-archiver.ts
index eb814ac7..90c929e2 100644
--- a/packages/deepagent-code/src/wiki/event-driven-archiver.ts
+++ b/packages/deepagent-code/src/wiki/event-driven-archiver.ts
@@ -1,6 +1,6 @@
 export * as EventDrivenArchiver from "./event-driven-archiver"
 
-import { Context, Effect, Layer, Stream, Schedule, Duration, Cause } from "effect"
+import { Context, Deferred, Effect, Layer, Stream, Schedule, Duration, Cause } from "effect"
 import { DeepAgentEventBus } from "@deepagent-code/core/deepagent/deepagent-event-bus"
 import { DeepAgentEvent } from "@deepagent-code/core/deepagent/deepagent-event"
 import { LMNEvents } from "@deepagent-code/core/deepagent/lmn-events"
@@ -121,9 +121,12 @@ export const layerWith = (options?: LayerOptions) =>
         })
 
       if (runLoop) {
+        yield* bus.registerConsumerGroup(ARCHIVE_GROUP)
+        const ready = yield* Deferred.make<void>()
         yield* bus
           .subscribe({ group: ARCHIVE_GROUP })
           .pipe(
+            Stream.onStart(Deferred.succeed(ready, undefined)),
             Stream.runForEach((event) =>
               handle(event).pipe(
                 Effect.catchCause((cause) =>
@@ -134,6 +137,7 @@ export const layerWith = (options?: LayerOptions) =>
             ),
             Effect.forkScoped,
           )
+        yield* Deferred.await(ready)
 
         yield* pumpRetries()
           .pipe(
diff --git a/packages/deepagent-code/test/cli/mcp-add.test.ts b/packages/deepagent-code/test/cli/mcp-add.test.ts
index c9f5d680..427af4b5 100644
--- a/packages/deepagent-code/test/cli/mcp-add.test.ts
+++ b/packages/deepagent-code/test/cli/mcp-add.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect } from "bun:test"
 import { Effect } from "effect"
+import { parse } from "jsonc-parser"
 import path from "path"
 import { cliIt } from "../lib/cli-process"
 
@@ -21,9 +22,8 @@ describe("deepagentCode mcp add (non-interactive subprocess)", () => {
         ])
         deepagentCode.expectExit(result, 0)
 
-        const config = yield* Effect.promise(() =>
-          Bun.file(path.join(home, ".config", "deepagent-code", "deepagent-code.json")).json(),
-        )
+        const configPath = path.join(home, ".deepagent", "code", "config.jsonc")
+        const config = parse(yield* Effect.promise(() => Bun.file(configPath).text()))
         expect(config.mcp.github).toEqual({
           type: "remote",
           url: "https://example.com/mcp",
@@ -32,6 +32,9 @@ describe("deepagentCode mcp add (non-interactive subprocess)", () => {
             "X-Option": "one=two",
           },
         })
+        expect(
+          yield* Effect.promise(() => Bun.file(path.join(home, ".config", "deepagent-code", "deepagent-code.json")).exists()),
+        ).toBe(false)
       }),
     60_000,
   )
@@ -57,9 +60,8 @@ describe("deepagentCode mcp add (non-interactive subprocess)", () => {
         ])
         deepagentCode.expectExit(result, 0)
 
-        const config = yield* Effect.promise(() =>
-          Bun.file(path.join(home, ".config", "deepagent-code", "deepagent-code.json")).json(),
-        )
+        const configPath = path.join(home, ".deepagent", "code", "config.jsonc")
+        const config = parse(yield* Effect.promise(() => Bun.file(configPath).text()))
         expect(config.mcp.local).toEqual({
           type: "local",
           command: ["npx", "-y", "@example/server", "--label", "two words"],
@@ -68,6 +70,9 @@ describe("deepagentCode mcp add (non-interactive subprocess)", () => {
             VALUE: "one=two",
           },
         })
+        expect(
+          yield* Effect.promise(() => Bun.file(path.join(home, ".config", "deepagent-code", "deepagent-code.json")).exists()),
+        ).toBe(false)
       }),
     60_000,
   )
diff --git a/packages/deepagent-code/test/provider/transform.test.ts b/packages/deepagent-code/test/provider/transform.test.ts
index b09ce0bd..d27457a3 100644
--- a/packages/deepagent-code/test/provider/transform.test.ts
+++ b/packages/deepagent-code/test/provider/transform.test.ts
@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test"
 import { Effect } from "effect"
 import { ProviderTransform } from "@/provider/transform"
 import { LLMRequestPrep } from "@/session/llm/request"
+import { AgentGateway } from "@deepagent-code/core/agent-gateway"
 import { ProviderV2 } from "@deepagent-code/core/provider"
 import { ModelV2 } from "@deepagent-code/core/model"
 
@@ -334,6 +335,9 @@ describe("ProviderTransform.options - gpt-5 textVerbosity", () => {
   })
 
   test("azure chat completions omit Responses-only reasoning options after variants merge", async () => {
+    // Disable deepagent mode so the prepare path skips renderPlanStatus (which requires
+    // SessionState.configure/planStoreRoot and is orthogonal to what this test exercises).
+    AgentGateway.configure({ enabled: false })
     const model = {
       ...createGpt5Model("gpt-5.4"),
       id: "azure/gpt-5.4",
@@ -2529,8 +2533,9 @@ describe("ProviderTransform.variants", () => {
   })
 
   // Bug fix: gpt-5.x models on @ai-sdk/openai-compatible endpoints now get the extended
-  // effort set (xhigh from gpt-5.2+). Previously the adapter always returned low/medium/high.
-  test("openai-compatible gpt-5.6-sol returns xhigh reasoning effort", () => {
+  // effort set (xhigh from gpt-5.2+). `none` and `minimal` are filtered out — they are
+  // Responses-API-only tiers that compatible endpoints do not implement.
+  test("openai-compatible gpt-5.6-sol returns xhigh but not none/minimal", () => {
     const model = createMockModel({
       id: "cortecs/gpt-5.6-sol",
       providerID: "cortecs",
@@ -2541,7 +2546,25 @@ describe("ProviderTransform.variants", () => {
       },
     })
     const result = ProviderTransform.variants(model)
-    expect(Object.keys(result)).toEqual(["none", "low", "medium", "high", "xhigh"])
+    expect(Object.keys(result)).toEqual(["low", "medium", "high", "xhigh"])
+    expect(result.xhigh).toEqual({ reasoningEffort: "xhigh" })
+    expect(result.none).toBeUndefined()
+  })
+
+  // Bug fix: Anthropic models (Claude family) routed via an openai-compatible gateway now get the
+  // full adaptive effort set including xhigh, expressed as reasoningEffort for the gateway to forward.
+  test("openai-compatible claude-fable-5 returns adaptive efforts including xhigh", () => {
+    const model = createMockModel({
+      id: "gateway/claude-fable-5",
+      providerID: "gateway",
+      api: {
+        id: "claude-fable-5",
+        url: "https://api.gateway.ai/v1",
+        npm: "@ai-sdk/openai-compatible",
+      },
+    })
+    const result = ProviderTransform.variants(model)
+    expect(Object.keys(result)).toEqual(["low", "medium", "high", "xhigh", "max"])
     expect(result.xhigh).toEqual({ reasoningEffort: "xhigh" })
   })
 
diff --git a/packages/deepagent-code/test/session/structured-output.test.ts b/packages/deepagent-code/test/session/structured-output.test.ts
index 8e46d393..563ab530 100644
--- a/packages/deepagent-code/test/session/structured-output.test.ts
+++ b/packages/deepagent-code/test/session/structured-output.test.ts
@@ -469,3 +469,73 @@ describe("structured-output.createStructuredOutputTool", () => {
   // The tool simply calls onSuccess when execute() is called with valid args
   // See prompt.ts loop() for actual retry logic
 })
+
+// P1: schema-aware system prompt — injects top-level field names so the model knows
+// the exact fields during extended-thinking (xhigh) reasoning, preventing the
+// infinite loop caused by the model guessing wrong field names (e.g. "summary" instead
+// of "module" for ResearchResult).
+describe("structured-output.buildStructuredOutputSystemPrompt", () => {
+  test("includes field names in the prompt", () => {
+    const result = SessionPrompt.buildStructuredOutputSystemPrompt({
+      type: "object",
+      properties: {
+        module: { type: "string" },
+        mechanism: { type: "string" },
+        keyFiles: { type: "array" },
+      },
+    })
+    expect(result).toContain("module")
+    expect(result).toContain("mechanism")
+    expect(result).toContain("keyFiles")
+    expect(result).toContain("StructuredOutput")
+  })
+
+  test("falls back gracefully when schema has no properties", () => {
+    const result = SessionPrompt.buildStructuredOutputSystemPrompt({ type: "object" })
+    expect(result).toContain("StructuredOutput")
+    // should not contain a field hint line
+    expect(result).not.toContain("Required fields:")
+  })
+
+  test("falls back gracefully for empty schema", () => {
+    const result = SessionPrompt.buildStructuredOutputSystemPrompt({})
+    expect(result).toContain("StructuredOutput")
+    expect(result).not.toContain("Required fields:")
+  })
+
+  test("uses ONLY exact field names, not descriptions or types", () => {
+    const result = SessionPrompt.buildStructuredOutputSystemPrompt({
+      type: "object",
+      properties: {
+        summary: { type: "string", description: "A long description here" },
+        findings: { type: "array" },
+      },
+    })
+    expect(result).toContain("summary")
+    expect(result).toContain("findings")
+    // should not leak the description text into the prompt
+    expect(result).not.toContain("A long description here")
+  })
+})
+
+// P0: extractSchemaTopLevelFields — utility that drives both the system-prompt injection
+// and the retry-cap corrective hint.
+describe("structured-output.extractSchemaTopLevelFields", () => {
+  test("returns top-level property names", () => {
+    const fields = SessionPrompt.extractSchemaTopLevelFields({
+      type: "object",
+      properties: { module: {}, mechanism: {}, keyFiles: {} },
+    })
+    expect(fields).toEqual(["module", "mechanism", "keyFiles"])
+  })
+
+  test("returns empty array when no properties", () => {
+    expect(SessionPrompt.extractSchemaTopLevelFields({ type: "object" })).toEqual([])
+    expect(SessionPrompt.extractSchemaTopLevelFields({})).toEqual([])
+  })
+
+  test("returns empty array for non-object/null schema", () => {
+    expect(SessionPrompt.extractSchemaTopLevelFields(null as any)).toEqual([])
+    expect(SessionPrompt.extractSchemaTopLevelFields(undefined as any)).toEqual([])
+  })
+})
diff --git a/packages/deepagent-code/test/tool/task-status.test.ts b/packages/deepagent-code/test/tool/task-status.test.ts
index af371747..cd3976d5 100644
--- a/packages/deepagent-code/test/tool/task-status.test.ts
+++ b/packages/deepagent-code/test/tool/task-status.test.ts
@@ -17,6 +17,7 @@ import { RuntimeFlags } from "@/effect/runtime-flags"
 import { disposeAllInstances } from "../fixture/fixture"
 import { pollWithTimeout, testEffect } from "../lib/effect"
 
+// Task-status reads durable child sessions; BackgroundJob only overlays live work.
 afterEach(async () => {
   await disposeAllInstances()
 })
@@ -38,9 +39,6 @@ const it = testEffect(
   ),
 )
 
-const mine = SessionID.make("ses_task_status_mine")
-const other = SessionID.make("ses_task_status_other")
-
 const execCtx = (sessionID: SessionID) => ({
   sessionID,
   messageID: MessageID.ascending(),
@@ -55,48 +53,38 @@ const execCtx = (sessionID: SessionID) => ({
 describe("tool.task_status (v4.0.4 block1 1c)", () => {
   it.instance("lists this session's dispatched subagents with status, and hides other sessions'", () =>
     Effect.gen(function* () {
+      const sessions = yield* Session.Service
       const jobs = yield* BackgroundJob.Service
-      yield* jobs.start({
-        id: "job-task-status-running",
-        type: "task",
-        title: "first task",
-        metadata: { parentSessionId: mine, sessionId: "job-task-status-running" },
-        run: Effect.never,
+      const parent = yield* sessions.create({ title: "Parent" })
+      const running = yield* sessions.create({ parentID: parent.id, agent: "general", title: "first task" })
+      const terminal = yield* sessions.create({ parentID: parent.id, agent: "general", title: "second task" })
+      yield* sessions.create({ parentID: parent.id, title: "ordinary child" })
+      const unrelatedParent = yield* sessions.create({ title: "Other parent" })
+      yield* sessions.create({ parentID: unrelatedParent.id, agent: "general", title: "someone else's task" })
+      yield* sessions.setMetadata({
+        sessionID: terminal.id,
+        metadata: { deepagent: { subagent: { finished: true, state: "error" } } },
       })
       yield* jobs.start({
-        id: "job-task-status-settled",
+        id: running.id,
         type: "task",
-        title: "second task",
-        metadata: { parentSessionId: mine, sessionId: "job-task-status-settled" },
-        run: Effect.fail(new Error("boom")),
-      })
-      yield* jobs.start({
-        id: "job-task-status-other",
-        type: "task",
-        title: "someone else's task",
-        metadata: { parentSessionId: other, sessionId: "job-task-status-other" },
+        title: "first task",
+        metadata: { parentSessionId: parent.id, sessionId: running.id, subagentType: "general" },
         run: Effect.never,
       })
-      yield* pollWithTimeout(
-        Effect.gen(function* () {
-          const job = yield* jobs.get("job-task-status-settled")
-          return job?.status === "error" ? (true as const) : undefined
-        }),
-        "settled job never reached terminal state",
-      )
 
       const tool = yield* TaskStatusTool
       const def = yield* tool.init()
-      const result = yield* def.execute({}, execCtx(mine))
+      const result = yield* def.execute({}, execCtx(parent.id))
 
-      expect(result.metadata.count).toBe(2)
+      expect(result.metadata.count).toBe(3)
       expect(result.output).toContain("[running]")
       expect(result.output).toContain("first task")
-      expect(result.output).toContain("job-task-status-running")
+      expect(result.output).toContain(running.id)
       expect(result.output).toContain("[error]")
       expect(result.output).toContain("second task")
+      expect(result.output).toContain("ordinary child")
       expect(result.output).not.toContain("someone else's task")
-      expect(result.output).not.toContain("job-task-status-other")
     }),
   )
 
@@ -111,38 +99,17 @@ describe("tool.task_status (v4.0.4 block1 1c)", () => {
     }),
   )
 
-  // 1c regression: BackgroundJob records type="task" for EVERY dispatch, so the list must surface the
-  // real subagent type from metadata.subagentType — otherwise every row reads "task" and the parent
-  // cannot tell WHICH subagent hung (the whole point of the tool). Falls back to job.type only when the
-  // metadata is absent (older jobs).
-  it.instance("names the real subagent type from metadata, falling back to job.type", () =>
+  it.instance("names durable subagents by their session agent", () =>
     Effect.gen(function* () {
-      const sess = SessionID.make("ses_task_status_types")
-      const jobs = yield* BackgroundJob.Service
-      yield* jobs.start({
-        id: "job-typed-reviewer",
-        type: "task",
-        title: "review the diff",
-        metadata: { parentSessionId: sess, sessionId: "job-typed-reviewer", subagentType: "reviewer" },
-        run: Effect.never,
-      })
-      yield* jobs.start({
-        id: "job-untyped",
-        type: "task",
-        title: "legacy job",
-        metadata: { parentSessionId: sess, sessionId: "job-untyped" },
-        run: Effect.never,
-      })
+      const sessions = yield* Session.Service
+      const parent = yield* sessions.create({ title: "Parent" })
+      yield* sessions.create({ parentID: parent.id, agent: "reviewer", title: "review the diff" })
 
       const tool = yield* TaskStatusTool
       const def = yield* tool.init()
-      const result = yield* def.execute({}, execCtx(sess))
+      const result = yield* def.execute({}, execCtx(parent.id))
 
-      // The reviewer row is named by its real type, not the generic "task".
-      expect(result.output).toContain("reviewer")
       expect(result.output).toContain('reviewer "review the diff"')
-      // The untyped legacy job still falls back to job.type ("task").
-      expect(result.output).toContain('task "legacy job"')
     }),
   )
 })
diff --git a/packages/deepagent-code/test/tool/task-takeover.test.ts b/packages/deepagent-code/test/tool/task-takeover.test.ts
index 84479583..2f8f2f06 100644
--- a/packages/deepagent-code/test/tool/task-takeover.test.ts
+++ b/packages/deepagent-code/test/tool/task-takeover.test.ts
@@ -78,6 +78,9 @@ const takeoverOnce = testEffect(layer({ subagentTimeoutMs: 50, subagentTakeoverL
 const takeoverWorktree = testEffect(
   Layer.mergeAll(layer({ subagentTimeoutMs: 50, subagentTakeoverLimit: 1 }), worktreeMock),
 )
+const takeoverBackgroundWorktree = testEffect(
+  Layer.mergeAll(layer({ subagentTimeoutMs: 50, subagentTakeoverLimit: 2 }), worktreeMock),
+)
 const e2e = testEffect(
   Layer.mergeAll(
     layer({ subagentTimeoutMs: 50, subagentTakeoverLimit: 2, subagentOutputMaxChars: 10 }),
@@ -302,8 +305,9 @@ describe("tool.task takeover (v4.0.4 block1 1a+1b)", () => {
     }),
   )
 
-  takeover.instance("background tasks drive the timeout-takeover-inject chain end to end", () =>
+  takeoverBackgroundWorktree.instance("background tasks drive the timeout-takeover-inject chain end to end", () =>
     Effect.gen(function* () {
+      resetWorktreeLog()
       const jobs = yield* BackgroundJob.Service
       const { chat, assistant } = yield* seed()
       const tool = yield* TaskTool
@@ -327,6 +331,7 @@ describe("tool.task takeover (v4.0.4 block1 1a+1b)", () => {
           prompt: "look into the cache key path",
           subagent_type: "general",
           background: true,
+          isolation: "worktree",
         },
         execCtx(chat, assistant, promptOps),
       )
@@ -345,6 +350,9 @@ describe("tool.task takeover (v4.0.4 block1 1a+1b)", () => {
       expect(injected.length).toBeGreaterThan(0)
       expect(injected[0]).toContain("background recovered")
       expect(injected[0]).toContain("takeover")
+      expect(wt.created).toHaveLength(2)
+      expect(wt.removed).toEqual([wt.created[0]])
+      expect(wt.safeRemoved).toEqual([wt.created[1]])
     }),
   )
 
diff --git a/packages/desktop/package.json b/packages/desktop/package.json
index 917be9ac..531c7962 100644
--- a/packages/desktop/package.json
+++ b/packages/desktop/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@deepagent-code/desktop",
   "private": true,
-  "version": "1.4.2",
+  "version": "1.4.3",
   "type": "module",
   "license": "AGPL-3.0-or-later",
   "homepage": "https://deepagent-code.ai",
diff --git a/packages/desktop/src/main/index.ts b/packages/desktop/src/main/index.ts
index 5d2c8b87..6fef738e 100644
--- a/packages/desktop/src/main/index.ts
+++ b/packages/desktop/src/main/index.ts
@@ -345,13 +345,19 @@ const main = Effect.gen(function* () {
       void wslServers.initialize().catch((error) => logger.error("wsl server initialization failed", error))
     }
 
+    // Wait for the sidecar to be ready for API requests before delivering credentials
+    // to the renderer. Listener-ready ≠ API-ready; delivering credentials too early
+    // causes the renderer to race against an uninitialized sidecar, which can result
+    // in failed bootstrap requests and a "local server disconnected" splash.
+    // Timeout is 15 s (down from the old 30 s). On failure we log and continue.
     yield* Effect.promise(() => health.wait).pipe(
-      Effect.timeout("30 seconds"),
+      Effect.timeout("15 seconds"),
       Effect.tapError((e) =>
         Effect.sync(() => {
           logger.error("sidecar health check failed", e.toString())
         }),
       ),
+      Effect.ignore,
     )
 
     yield* Deferred.succeed(serverReady, {
diff --git a/packages/desktop/src/main/sidecar.ts b/packages/desktop/src/main/sidecar.ts
index 4a9502cf..f0fc1392 100644
--- a/packages/desktop/src/main/sidecar.ts
+++ b/packages/desktop/src/main/sidecar.ts
@@ -38,6 +38,13 @@ type Listener = {
 const parentPort = getParentPort()
 let listener: Listener | undefined
 
+// Eagerly start loading the server module the instant the sidecar process
+// starts — before the {type:"start"} message arrives from the main process.
+// Module loading (parsing + JIT) takes 1-2 s; starting it here lets that
+// work overlap with the main process's loadShellEnv + window creation, so
+// by the time start() is called the import is already done or nearly done.
+const serverModulePromise = import("virtual:deepagent-code-server")
+
 parentPort.on("message", (event) => {
   const command = parseCommand(event.data)
   if (!command) return
@@ -54,7 +61,8 @@ async function start(command: StartCommand) {
     ensureLoopbackNoProxy()
     useSystemCertificates()
     useEnvProxy()
-    const { Log, Server } = await import("virtual:deepagent-code-server")
+    // Await the eagerly-started import — usually already done by now.
+    const { Log, Server } = await serverModulePromise
     await Log.init({ level: "WARN" })
 
     listener = await Server.listen({

From 6906ee62f7171abb2c4f66696baa58316039124d Mon Sep 17 00:00:00 2001
From: thomas <odie_majere@outlook.com>
Date: Wed, 22 Jul 2026 22:48:02 +0800
Subject: [PATCH 4/5] =?UTF-8?q?feat(cli):=20Server=20Edition=20server-mode?=
 =?UTF-8?q?=20=E2=80=94=20gateway=20login/workspace=20commands,=20remote?=
 =?UTF-8?q?=20transport,=20headless=20entry=20hardening=20(#81)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

### Issue for this PR

Closes #

### Type of change

- [ ] Bug fix
- [x] New feature
- [ ] Refactor / code improvement
- [ ] Documentation

### What does this PR do?

This PR prepares the new CLI (`packages/cli`, `dacode`) and the headless
server to act as a client/data-plane for DeepAgent Server Edition
(design: server-v1 §11/§13/§20). The CLI now connects to a gateway with
JWT auth and routes workspace traffic through the `/w/:workspaceId`
transparent proxy instead of a local daemon.

**CLI changes:**
- `dacode login [gateway] [--email --password]` / `logout` –
authenticate via `POST /control/v1/auth/login`, store state in
`~/.deepagent/code/state/server-mode.json` (0600, atomic temp+rename).
Flags optional; fallback to interactive prompts. Refresh token read from
response body, with `Set-Cookie` as fallback.
- `dacode workspace list` / `dacode workspace use <id>` – list gateway
workspaces and pin a selection; remote base URL becomes
`{gateway}/w/{workspaceId}`.
- The `Connection` service switches to remote transport when server-mode
is active; otherwise uses the existing local daemon (unchanged
behavior).
- Remote transport is a fetch wrapper that injects `Authorization:
Bearer` and, on 401, performs a single-flight token refresh with one
retry. Since the TUI already accepts a custom `fetch`, all TUI/SDK
traffic (including SSE) gets auth + reconnect without any changes to
`packages/tui`.
- `DEEPAGENT_GATEWAY_URL` pins the gateway (server-v1 §20.3
auto-switch); a mismatch with stored login produces a clear error
suggesting `dacode login <url>`.

**Server changes (`packages/deepagent-code`):**
- Add explicit `"./server"` subpath export so `import { listen, openapi
} from "deepagent-code/server"` resolves as documented for the
workspace-agent.
- `/global/capabilities` gains an optional `commit` field from
`DEEPAGENT_CODE_COMMIT` (injected by CI for version-checking, §13.3).
Omitted in local builds; optional in schema for backward compatibility.
- `DEEPAGENT_SERVER_MODE=true` makes `Auth.set`/`Auth.remove` fail with
a clear error – in gateway-managed containers, provider keys come via
env and must not persist to volume (§20.4). Reads (including
`DEEPAGENT_CODE_AUTH_CONTENT`) are unaffected.

> **Note:** The gateway itself (`deepagent-code-server` repo) is not
implemented yet; the refresh-cookie contract may need a follow-up once
the real gateway exists.

### How did you verify your code works?

- `bun typecheck` passes for `packages/cli`, `packages/core`,
`packages/deepagent-code`.
- End-to-end against a mock gateway (`Bun.serve` implementing auth
endpoints, workspace listing, and proxy paths): covered login via
args/env, state file permissions, workspace list/use with expired token
refresh, remote transport URL and auth injection, logout, and gateway
mismatch errors.
- Server tests: started the legacy server via the new subpath export,
confirmed `/global/capabilities` returns the injected commit and
`openapi()` works; `Auth.set`/`Auth.remove` are blocked under
`DEEPAGENT_SERVER_MODE=true`; without it `auth.json` is written with
mode 600.
- Existing related suites pass: `test/auth/auth.test.ts`,
`test/server/httpapi-global.test.ts`,
`test/server/httpapi-public-openapi.test.ts`.
(`test/server/httpapi-listen.test.ts` has PTY failures that reproduce
identically on the base commit in this environment.)

### Screenshots / recordings

_No UI changes._

### Checklist

- [x] I have tested my changes locally
- [x] I have not included unrelated changes in this PR

---------

Co-authored-by: deepagent-ai <jamessmithm539@gmail.com>
---
 packages/cli/package.json                     |   4 +-
 packages/cli/src/commands/commands.ts         |  19 +
 packages/cli/src/commands/handlers/default.ts |   6 +-
 packages/cli/src/commands/handlers/login.ts   |  43 +++
 packages/cli/src/commands/handlers/logout.ts  |  13 +
 .../src/commands/handlers/workspace/list.ts   |  23 ++
 .../src/commands/handlers/workspace/use.ts    |  13 +
 packages/cli/src/framework/runtime.ts         |  10 +-
 packages/cli/src/index.ts                     |  10 +
 packages/cli/src/services/connection.ts       |  38 ++
 packages/cli/src/services/graceful-fetch.ts   |  26 ++
 packages/cli/src/services/server-mode.ts      | 315 +++++++++++++++
 packages/cli/src/tui.ts                       |  27 +-
 packages/cli/test/connection.test.ts          | 121 ++++++
 packages/cli/test/graceful-fetch.test.ts      |  61 +++
 packages/cli/test/handlers.test.ts            | 145 +++++++
 packages/cli/test/server-mode.test.ts         | 364 ++++++++++++++++++
 packages/core/src/flag/flag.ts                |   9 +
 packages/deepagent-code/package.json          |   1 +
 packages/deepagent-code/src/auth/index.ts     |  13 +
 .../routes/instance/httpapi/groups/global.ts  |   3 +
 .../instance/httpapi/handlers/global.ts       |   2 +
 .../deepagent-code/test/auth/auth.test.ts     |  31 +-
 23 files changed, 1269 insertions(+), 28 deletions(-)
 create mode 100644 packages/cli/src/commands/handlers/login.ts
 create mode 100644 packages/cli/src/commands/handlers/logout.ts
 create mode 100644 packages/cli/src/commands/handlers/workspace/list.ts
 create mode 100644 packages/cli/src/commands/handlers/workspace/use.ts
 create mode 100644 packages/cli/src/services/connection.ts
 create mode 100644 packages/cli/src/services/graceful-fetch.ts
 create mode 100644 packages/cli/src/services/server-mode.ts
 create mode 100644 packages/cli/test/connection.test.ts
 create mode 100644 packages/cli/test/graceful-fetch.test.ts
 create mode 100644 packages/cli/test/handlers.test.ts
 create mode 100644 packages/cli/test/server-mode.test.ts

diff --git a/packages/cli/package.json b/packages/cli/package.json
index 05b70c77..a7e8a243 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -14,7 +14,9 @@
   "scripts": {
     "build": "bun run script/build.ts",
     "dev": "bun run src/index.ts",
-    "typecheck": "tsgo --noEmit"
+    "typecheck": "tsgo --noEmit",
+    "test": "bun test --timeout 30000",
+    "test:ci": "mkdir -p .artifacts/unit && bun test --timeout 30000 --reporter=junit --reporter-outfile=.artifacts/unit/junit.xml"
   },
   "dependencies": {
     "@effect/platform-node": "catalog:",
diff --git a/packages/cli/src/commands/commands.ts b/packages/cli/src/commands/commands.ts
index 3f70742c..fb676f2d 100644
--- a/packages/cli/src/commands/commands.ts
+++ b/packages/cli/src/commands/commands.ts
@@ -12,6 +12,25 @@ export const Commands = Spec.make(
         description: "Debugging and troubleshooting tools",
         commands: [Spec.make("agents", { description: "List all agents" })],
       }),
+      Spec.make("login", {
+        description: "Log in to a DeepAgent Server gateway (server mode)",
+        params: {
+          gateway: Argument.string("gateway").pipe(Argument.optional),
+          email: Flag.string("email").pipe(Flag.optional),
+          password: Flag.string("password").pipe(Flag.optional),
+        },
+      }),
+      Spec.make("logout", { description: "Log out of the DeepAgent Server gateway" }),
+      Spec.make("workspace", {
+        description: "Manage DeepAgent Server workspaces (server mode)",
+        commands: [
+          Spec.make("list", { description: "List workspaces on the gateway" }),
+          Spec.make("use", {
+            description: "Select the workspace to connect to",
+            params: { id: Argument.string("id") },
+          }),
+        ],
+      }),
       Spec.make("migrate", { description: "Migrate v1 data to v2" }),
       Spec.make("service", {
         description: "Manage the background server",
diff --git a/packages/cli/src/commands/handlers/default.ts b/packages/cli/src/commands/handlers/default.ts
index d0a9968e..380de881 100644
--- a/packages/cli/src/commands/handlers/default.ts
+++ b/packages/cli/src/commands/handlers/default.ts
@@ -1,12 +1,12 @@
 import { Commands } from "../commands"
 import { Runtime } from "../../framework/runtime"
 import { Effect } from "effect"
-import { Daemon } from "../../services/daemon"
+import { Connection } from "../../services/connection"
 
 export default Runtime.handler(Commands, () =>
   Effect.gen(function* () {
-    const daemon = yield* Daemon.Service
-    const transport = yield* daemon.transport()
+    const connection = yield* Connection.Service
+    const transport = yield* connection.transport()
     const { runTui } = yield* Effect.promise(() => import("../../tui"))
     yield* runTui(transport)
   }),
diff --git a/packages/cli/src/commands/handlers/login.ts b/packages/cli/src/commands/handlers/login.ts
new file mode 100644
index 00000000..8e7bf1ba
--- /dev/null
+++ b/packages/cli/src/commands/handlers/login.ts
@@ -0,0 +1,43 @@
+import { EOL } from "os"
+import * as Effect from "effect/Effect"
+import * as NodeServices from "@effect/platform-node/NodeServices"
+import { Option, Redacted } from "effect"
+import { Prompt } from "effect/unstable/cli"
+import { Commands } from "../commands"
+import { Runtime } from "../../framework/runtime"
+import { ServerMode } from "../../services/server-mode"
+
+export default Runtime.handler(
+  Commands.commands.login,
+  Effect.fn("cli.login")(function* (input) {
+    const serverMode = yield* ServerMode.Service
+    const gateway = Option.getOrUndefined(input.gateway) ?? process.env.DEEPAGENT_GATEWAY_URL
+    if (gateway === undefined)
+      return yield* Effect.fail(
+        new Error("Gateway URL required. Pass it as an argument or set DEEPAGENT_GATEWAY_URL."),
+      )
+    const url = gateway.replace(/\/+$/, "")
+    const email = yield* Option.match(input.email, {
+      onNone: () =>
+        Prompt.run(Prompt.text({ message: "Email" })).pipe(
+          Effect.provide(NodeServices.layer),
+          Effect.mapError(() => new Error("Login cancelled")),
+        ),
+      onSome: Effect.succeed,
+    })
+    const password = yield* Option.match(input.password, {
+      onNone: () =>
+        Prompt.run(Prompt.password({ message: "Password" })).pipe(
+          Effect.provide(NodeServices.layer),
+          Effect.map(Redacted.value),
+          Effect.mapError(() => new Error("Login cancelled")),
+        ),
+      onSome: Effect.succeed,
+    })
+    const state = yield* serverMode.login(url, email, password)
+    process.stdout.write(
+      `Logged in to ${state.gatewayUrl} as ${email}.${state.workspaceId ? "" : " Run `dacode workspace list` to pick a workspace."}` +
+        EOL,
+    )
+  }),
+)
diff --git a/packages/cli/src/commands/handlers/logout.ts b/packages/cli/src/commands/handlers/logout.ts
new file mode 100644
index 00000000..757d69c6
--- /dev/null
+++ b/packages/cli/src/commands/handlers/logout.ts
@@ -0,0 +1,13 @@
+import { EOL } from "os"
+import * as Effect from "effect/Effect"
+import { Commands } from "../commands"
+import { Runtime } from "../../framework/runtime"
+import { ServerMode } from "../../services/server-mode"
+
+export default Runtime.handler(
+  Commands.commands.logout,
+  Effect.fn("cli.logout")(function* () {
+    yield* (yield* ServerMode.Service).logout()
+    process.stdout.write("Logged out." + EOL)
+  }),
+)
diff --git a/packages/cli/src/commands/handlers/workspace/list.ts b/packages/cli/src/commands/handlers/workspace/list.ts
new file mode 100644
index 00000000..2f0f717c
--- /dev/null
+++ b/packages/cli/src/commands/handlers/workspace/list.ts
@@ -0,0 +1,23 @@
+import { EOL } from "os"
+import * as Effect from "effect/Effect"
+import { Option } from "effect"
+import { Commands } from "../../commands"
+import { Runtime } from "../../../framework/runtime"
+import { ServerMode } from "../../../services/server-mode"
+
+export default Runtime.handler(
+  Commands.commands.workspace.commands.list,
+  Effect.fn("cli.workspace.list")(function* () {
+    const serverMode = yield* ServerMode.Service
+    const list = yield* serverMode.workspaces()
+    const current = yield* serverMode
+      .status()
+      .pipe(Effect.map((state) => (Option.isSome(state) ? state.value.workspaceId : undefined)))
+    list.forEach((workspace) => {
+      const selected = current === workspace.id ? "*" : " "
+      process.stdout.write(
+        `${selected} ${workspace.id}  ${workspace.name ?? "-"}  ${workspace.status ?? "-"}` + EOL,
+      )
+    })
+  }),
+)
diff --git a/packages/cli/src/commands/handlers/workspace/use.ts b/packages/cli/src/commands/handlers/workspace/use.ts
new file mode 100644
index 00000000..49f702b0
--- /dev/null
+++ b/packages/cli/src/commands/handlers/workspace/use.ts
@@ -0,0 +1,13 @@
+import { EOL } from "os"
+import * as Effect from "effect/Effect"
+import { Commands } from "../../commands"
+import { Runtime } from "../../../framework/runtime"
+import { ServerMode } from "../../../services/server-mode"
+
+export default Runtime.handler(
+  Commands.commands.workspace.commands.use,
+  Effect.fn("cli.workspace.use")(function* (input) {
+    const workspace = yield* (yield* ServerMode.Service).useWorkspace(input.id)
+    process.stdout.write(`Using workspace ${workspace.id}${workspace.name ? ` (${workspace.name})` : ""}.` + EOL)
+  }),
+)
diff --git a/packages/cli/src/framework/runtime.ts b/packages/cli/src/framework/runtime.ts
index 97247e4d..788c4f20 100644
--- a/packages/cli/src/framework/runtime.ts
+++ b/packages/cli/src/framework/runtime.ts
@@ -2,6 +2,8 @@ import * as Effect from "effect/Effect"
 import * as Command from "effect/unstable/cli/Command"
 import { Spec } from "./spec"
 import { Daemon } from "../services/daemon"
+import { ServerMode } from "../services/server-mode"
+import { Connection } from "../services/connection"
 
 export type Input<Value> =
   Value extends Spec.Node<infer _Name, infer Command, infer _Commands>
@@ -10,11 +12,13 @@ export type Input<Value> =
       ? Input
       : never
 
-type RuntimeHandler = (input: unknown) => Effect.Effect<void, unknown, Daemon.Service>
+export type Services = Daemon.Service | ServerMode.Service | Connection.Service
+
+type RuntimeHandler = (input: unknown) => Effect.Effect<void, unknown, Services>
 type Loader<Node extends Spec.Any> = () => Promise<{
-  default: (input: Input<Node>) => Effect.Effect<void, any, Daemon.Service>
+  default: (input: Input<Node>) => Effect.Effect<void, any, Services>
 }>
-type ProvidedCommand = Command.Command<string, unknown, unknown, unknown, Daemon.Service>
+type ProvidedCommand = Command.Command<string, unknown, unknown, unknown, Services>
 
 export type Handlers<Node extends Spec.Any> = keyof Node["commands"] extends never
   ? Loader<Node>
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index c15362ac..19d9d413 100755
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -5,13 +5,21 @@ import * as NodeServices from "@effect/platform-node/NodeServices"
 import * as Effect from "effect/Effect"
 import { Commands } from "./commands/commands"
 import { Runtime } from "./framework/runtime"
+import { Connection } from "./services/connection"
 import { Daemon } from "./services/daemon"
+import { ServerMode } from "./services/server-mode"
 
 const Handlers = Runtime.handlers(Commands, {
   $: () => import("./commands/handlers/default"),
   debug: {
     agents: () => import("./commands/handlers/debug/agents"),
   },
+  login: () => import("./commands/handlers/login"),
+  logout: () => import("./commands/handlers/logout"),
+  workspace: {
+    list: () => import("./commands/handlers/workspace/list"),
+    use: () => import("./commands/handlers/workspace/use"),
+  },
   migrate: () => import("./commands/handlers/migrate"),
   service: {
     start: () => import("./commands/handlers/service/start"),
@@ -24,6 +32,8 @@ const Handlers = Runtime.handlers(Commands, {
 })
 
 Runtime.run(Commands, Handlers, { version: "local" }).pipe(
+  Effect.provide(Connection.defaultLayer),
+  Effect.provide(ServerMode.defaultLayer),
   Effect.provide(Daemon.defaultLayer),
   Effect.provide(NodeServices.layer),
   Effect.scoped,
diff --git a/packages/cli/src/services/connection.ts b/packages/cli/src/services/connection.ts
new file mode 100644
index 00000000..0fd7bbee
--- /dev/null
+++ b/packages/cli/src/services/connection.ts
@@ -0,0 +1,38 @@
+import { Context, Effect, Layer, Option } from "effect"
+import { Daemon } from "./daemon"
+import { ServerMode } from "./server-mode"
+
+// The local daemon has no custom fetch, so Connection widens the server-mode
+// transport shape instead of redefining it.
+export interface Transport extends Omit<ServerMode.Transport, "fetch"> {
+  readonly fetch?: ServerMode.Transport["fetch"]
+}
+
+export interface Interface {
+  readonly transport: () => Effect.Effect<Transport, unknown>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@deepagent-code/cli/Connection") {}
+
+// Server mode (DeepAgent Server Edition gateway) takes precedence when active:
+// either DEEPAGENT_GATEWAY_URL is pinned or a server-mode login exists. Otherwise
+// fall back to the local background daemon.
+export const layer = Layer.effect(
+  Service,
+  Effect.gen(function* () {
+    const daemon = yield* Daemon.Service
+    const serverMode = yield* ServerMode.Service
+
+    const transport = Effect.fn("cli.connection.transport")(function* () {
+      const remote = yield* serverMode.transport()
+      if (Option.isSome(remote)) return remote.value
+      return yield* daemon.transport()
+    })
+
+    return Service.of({ transport })
+  }),
+)
+
+export const defaultLayer = layer
+
+export * as Connection from "./connection"
diff --git a/packages/cli/src/services/graceful-fetch.ts b/packages/cli/src/services/graceful-fetch.ts
new file mode 100644
index 00000000..961aba5c
--- /dev/null
+++ b/packages/cli/src/services/graceful-fetch.ts
@@ -0,0 +1,26 @@
+const legacyDefaults: Record<string, unknown> = {
+  "/config/providers": { providers: [], default: {} },
+  "/provider": { all: [], default: {}, connected: [] },
+  "/agent": [],
+  "/config": {},
+}
+
+// Older daemons miss a few config endpoints; answer those 404s with empty
+// defaults so the TUI still boots against them. Wraps any base fetch — the
+// local daemon's or the server-mode gateway transport's.
+export const gracefulFetch = (base: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>) =>
+  Object.assign(
+    async (input: RequestInfo | URL, init?: RequestInit) => {
+      const response = await base(input, init)
+      if (response.status !== 404) return response
+      // Server-mode requests arrive under the bare /w proxy prefix; strip it so
+      // the same legacy endpoints match in both daemon and gateway mode.
+      const pathname = new URL(input instanceof Request ? input.url : input).pathname.replace(/^\/w(?=\/|$)/, "")
+      const fallback = legacyDefaults[pathname]
+      if (fallback === undefined) return response
+      return Response.json(fallback)
+    },
+    { preconnect: fetch.preconnect },
+  )
+
+export * as GracefulFetch from "./graceful-fetch"
diff --git a/packages/cli/src/services/server-mode.ts b/packages/cli/src/services/server-mode.ts
new file mode 100644
index 00000000..746acb4a
--- /dev/null
+++ b/packages/cli/src/services/server-mode.ts
@@ -0,0 +1,315 @@
+import { Global } from "@deepagent-code/core/global"
+import { Context, Effect, FileSystem, Layer, Option, Schema } from "effect"
+import path from "path"
+
+export interface Transport {
+  readonly url: string
+  readonly headers: RequestInit["headers"]
+  readonly fetch: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
+}
+
+export interface Workspace {
+  readonly id: string
+  readonly name?: string
+  readonly status?: string
+}
+
+export interface Interface {
+  readonly status: () => Effect.Effect<Option.Option<State>>
+  readonly login: (gatewayUrl: string, email: string, password: string) => Effect.Effect<State, Error>
+  readonly logout: () => Effect.Effect<void>
+  readonly workspaces: () => Effect.Effect<readonly Workspace[], Error>
+  readonly useWorkspace: (id: string) => Effect.Effect<Workspace, Error>
+  readonly transport: () => Effect.Effect<Option.Option<Transport>, Error>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@deepagent-code/cli/ServerMode") {}
+
+const State = Schema.Struct({
+  gatewayUrl: Schema.String,
+  accessToken: Schema.String,
+  refreshToken: Schema.optional(Schema.String),
+  expiresAt: Schema.optional(Schema.Number),
+  workspaceId: Schema.optional(Schema.String),
+})
+type State = typeof State.Type
+
+export const layer = Layer.effect(
+  Service,
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem
+    const directory = Global.Path.state
+    const file = path.join(directory, "server-mode.json")
+
+    // A missing or corrupt state file decodes as "logged out" everywhere read
+    // is used via Effect.option; the next login rewrites the file.
+    const read = Effect.fnUntraced(function* () {
+      const text = yield* fs.readFileString(file)
+      return yield* Schema.decodeUnknownEffect(Schema.fromJsonString(State))(text)
+    })
+
+    const write = Effect.fnUntraced(function* (state: State) {
+      const temp = file + ".tmp"
+      yield* fs.makeDirectory(directory, { recursive: true })
+      yield* fs.writeFileString(temp, JSON.stringify(state), { mode: 0o600 })
+      yield* fs.rename(temp, file)
+    })
+
+    // DEEPAGENT_GATEWAY_URL pins the gateway (server-v1 §20.3 auto-switch). When
+    // set it takes precedence over the stored gateway; a mismatch means the user
+    // must log in against the pinned gateway first.
+    const resolve = Effect.fnUntraced(function* () {
+      const stored = yield* read().pipe(Effect.option)
+      // Normalize the same way login does, otherwise a trailing slash in the
+      // env var never matches the stored gateway and reads as "not logged in".
+      const pinned = process.env.DEEPAGENT_GATEWAY_URL?.replace(/\/+$/, "")
+      const gatewayUrl = pinned ?? (Option.isSome(stored) ? stored.value.gatewayUrl : undefined)
+      if (gatewayUrl === undefined) return Option.none<{ gatewayUrl: string; state: State }>()
+      if (Option.isNone(stored) || stored.value.gatewayUrl !== gatewayUrl) {
+        return yield* Effect.fail(
+          new Error(`Not logged in to ${gatewayUrl}. Run \`dacode login ${gatewayUrl}\` first.`),
+        )
+      }
+      return Option.some({ gatewayUrl, state: stored.value })
+    })
+
+    const gatewayError = (response: Response) =>
+      Effect.tryPromise(() => response.json()).pipe(
+        Effect.map((body): string => {
+          const error = (body as { error?: { message?: unknown } })?.error
+          return typeof error?.message === "string" ? error.message : `${response.status} ${response.statusText}`
+        }),
+        Effect.catch(() => Effect.succeed(`${response.status} ${response.statusText}`)),
+      )
+
+    const post = (url: string, init: RequestInit) =>
+      Effect.tryPromise({
+        try: () => fetch(url, init),
+        catch: () => new Error(`Gateway ${url} is unreachable`),
+      })
+
+    let refreshing: Promise<State> | undefined
+    const refresh = Effect.fn("cli.server-mode.refresh")(function* () {
+      const current = yield* read().pipe(
+        Effect.mapError(() => new Error("Session expired. Run `dacode login` again.")),
+      )
+      if (!current.refreshToken)
+        return yield* Effect.fail(new Error("Session expired. Run `dacode login` again."))
+      const response = yield* post(`${current.gatewayUrl}/control/v1/auth/refresh`, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${current.refreshToken}`,
+          cookie: `refresh_token=${current.refreshToken}`,
+        },
+      })
+      if (!response.ok)
+        return yield* Effect.fail(new Error("Session expired. Run `dacode login` again."))
+      const body = yield* Effect.tryPromise({
+        try: () => response.json() as Promise<Record<string, unknown>>,
+        catch: () => new Error("Gateway returned an invalid refresh response"),
+      })
+      // The gateway returns the access token as camelCase `accessToken` in the
+      // JSON body; the refresh token only ever travels as the HttpOnly cookie.
+      if (typeof body.accessToken !== "string")
+        return yield* Effect.fail(new Error("Gateway returned an invalid refresh response"))
+      const rotated = response.headers.get("set-cookie")?.match(/(?:^|;\s*)refresh_token=([^;]+)/)?.[1]
+      const next: State = {
+        ...current,
+        accessToken: body.accessToken,
+        refreshToken:
+          typeof body.refresh_token === "string" ? body.refresh_token : (rotated ?? current.refreshToken),
+        expiresAt:
+          typeof body.expires_in === "number" ? Date.now() + body.expires_in * 1000 : current.expiresAt,
+      }
+      yield* write(next)
+      return next
+    })
+
+    // Single-flight refresh shared by the Effect world (workspace commands) and
+    // the plain-fetch world (TUI transport), so concurrent 401s trigger one
+    // refresh round.
+    const refreshOnce = () =>
+      (refreshing ??= Effect.runPromise(refresh()).finally(() => (refreshing = undefined)))
+
+    const accessToken = Effect.fnUntraced(function* () {
+      const state = yield* read().pipe(Effect.mapError(() => new Error("Not logged in")))
+      if (state.expiresAt !== undefined && state.expiresAt < Date.now() + 30_000) {
+        return yield* Effect.tryPromise({
+          try: () => refreshOnce(),
+          catch: (cause) => (cause instanceof Error ? cause : new Error(String(cause))),
+        }).pipe(Effect.map((state) => state.accessToken))
+      }
+      return state.accessToken
+    })
+
+    const authed = Effect.fnUntraced(function* (url: string, init: RequestInit = {}) {
+      const token = yield* accessToken()
+      const send = (token: string) =>
+        Effect.tryPromise({
+          try: () => fetch(url, { ...init, headers: { ...init.headers, authorization: `Bearer ${token}` } }),
+          catch: () => new Error(`Gateway ${url} is unreachable`),
+        })
+      const first = yield* send(token)
+      if (first.status !== 401) return first
+      const refreshed = yield* Effect.tryPromise({
+        try: () => refreshOnce(),
+        catch: (cause) => (cause instanceof Error ? cause : new Error(String(cause))),
+      })
+      return yield* send(refreshed.accessToken)
+    })
+
+    const login = Effect.fn("cli.server-mode.login")(function* (
+      gatewayUrl: string,
+      email: string,
+      password: string,
+    ) {
+      const response = yield* post(`${gatewayUrl}/control/v1/auth/login`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ email, password }),
+      })
+      if (!response.ok) {
+        const message = yield* gatewayError(response)
+        return yield* Effect.fail(new Error(`Login failed: ${message}`))
+      }
+      const body = yield* Effect.tryPromise({
+        try: () => response.json() as Promise<Record<string, unknown>>,
+        catch: () => new Error("Gateway returned an invalid login response"),
+      })
+      if (typeof body.accessToken !== "string")
+        return yield* Effect.fail(new Error("Gateway returned an invalid login response"))
+      const cookie = response.headers.get("set-cookie") ?? undefined
+      const refreshToken =
+        typeof body.refresh_token === "string"
+          ? body.refresh_token
+          : cookie?.match(/(?:^|;\s*)refresh_token=([^;]+)/)?.[1]
+      // Re-login against the same gateway keeps the selected workspace;
+      // the container id survives credential rotation.
+      const previous = yield* read().pipe(Effect.option)
+      const state: State = {
+        gatewayUrl,
+        accessToken: body.accessToken,
+        refreshToken,
+        expiresAt: typeof body.expires_in === "number" ? Date.now() + body.expires_in * 1000 : undefined,
+        workspaceId:
+          Option.isSome(previous) && previous.value.gatewayUrl === gatewayUrl
+            ? previous.value.workspaceId
+            : undefined,
+      }
+      yield* write(state)
+      return state
+    })
+
+    const logout = Effect.fn("cli.server-mode.logout")(function* () {
+      const current = yield* read().pipe(Effect.option)
+      if (Option.isSome(current)) {
+        yield* Effect.tryPromise(() =>
+          fetch(`${current.value.gatewayUrl}/control/v1/auth/logout`, {
+            method: "POST",
+            headers: { authorization: `Bearer ${current.value.accessToken}` },
+          }),
+        ).pipe(Effect.ignore)
+      }
+      yield* fs.remove(file).pipe(Effect.ignore)
+    })
+
+    const workspaces = Effect.fn("cli.server-mode.workspaces")(function* () {
+      const resolved = yield* resolve()
+      if (Option.isNone(resolved)) return yield* Effect.fail(new Error("Not logged in"))
+      // The gateway maps each user to a single container (one workspace per
+      // user). GET 404 means none exists yet; POST is the idempotent ensure
+      // that provisions it (200 exists | 202 provisioning).
+      const found = yield* authed(`${resolved.value.gatewayUrl}/control/v1/containers`)
+      const response =
+        found.status === 404
+          ? yield* authed(`${resolved.value.gatewayUrl}/control/v1/containers`, {
+              method: "POST",
+              headers: { "content-type": "application/json" },
+              body: "{}",
+            })
+          : found
+      if (!response.ok) {
+        const message = yield* gatewayError(response)
+        return yield* Effect.fail(new Error(`Failed to list workspaces: ${message}`))
+      }
+      const body = yield* Effect.tryPromise({
+        try: () => response.json() as Promise<{ id?: unknown; status?: unknown }>,
+        catch: () => new Error("Gateway returned an invalid workspaces response"),
+      })
+      if (typeof body.id !== "string")
+        return yield* Effect.fail(new Error("Gateway returned an invalid workspaces response"))
+      return [
+        {
+          id: body.id,
+          name: undefined,
+          status: typeof body.status === "string" ? body.status : undefined,
+        },
+      ]
+    })
+
+    const useWorkspace = Effect.fn("cli.server-mode.useWorkspace")(function* (id: string) {
+      const list = yield* workspaces()
+      const found = list.find((workspace) => workspace.id === id)
+      if (!found)
+        return yield* Effect.fail(
+          new Error(`Workspace ${id} not found. Run \`dacode workspace list\` to see available workspaces.`),
+        )
+      const current = yield* read().pipe(Effect.mapError(() => new Error("Not logged in")))
+      yield* write({ ...current, workspaceId: id })
+      return found
+    })
+
+    const transport = Effect.fn("cli.server-mode.transport")(function* () {
+      // A pinned gateway without a matching login must not brick local usage:
+      // warn and return none so Connection falls back to the local daemon.
+      // Command paths (workspaces, useWorkspace) keep the fail-fast login hint.
+      const resolved = yield* resolve().pipe(
+        Effect.catch((error) =>
+          Effect.sync(() => {
+            process.stderr.write(`${error.message} Falling back to the local daemon.\n`)
+            return Option.none<{ gatewayUrl: string; state: State }>()
+          }),
+        ),
+      )
+      if (Option.isNone(resolved)) return Option.none()
+      if (!resolved.value.state.workspaceId)
+        return yield* Effect.fail(
+          new Error(
+            "No workspace selected. Run `dacode workspace list` and `dacode workspace use <id>` first.",
+          ),
+        )
+      const remote = async (input: RequestInfo | URL, init?: RequestInit) => {
+        // The SDK hands us a single Request object whose body the first
+        // attempt consumes; clone upfront so the 401 retry stays replayable.
+        const retry = input instanceof Request && input.body !== null ? input.clone() : input
+        const send = (token: string, source: RequestInfo | URL) => {
+          const headers = new Headers(source instanceof Request ? source.headers : undefined)
+          new Headers(init?.headers).forEach((value, key) => headers.set(key, value))
+          headers.set("authorization", `Bearer ${token}`)
+          return fetch(source, { ...init, headers })
+        }
+        const first = await send(await Effect.runPromise(accessToken()), input)
+        if (first.status !== 401) return first
+        const refreshed = await refreshOnce()
+        return send(refreshed.accessToken, retry)
+      }
+      // The data-plane proxy locates the caller's container from the JWT, so
+      // the base URL is a bare `/w` without a workspace id segment.
+      return Option.some({
+        url: `${resolved.value.gatewayUrl}/w`,
+        headers: {},
+        fetch: remote,
+      })
+    })
+
+    const status = Effect.fn("cli.server-mode.status")(function* () {
+      return yield* read().pipe(Effect.option)
+    })
+
+    return Service.of({ status, login, logout, workspaces, useWorkspace, transport })
+  }),
+)
+
+export const defaultLayer = layer
+
+export * as ServerMode from "./server-mode"
diff --git a/packages/cli/src/tui.ts b/packages/cli/src/tui.ts
index 31312d99..927445bd 100644
--- a/packages/cli/src/tui.ts
+++ b/packages/cli/src/tui.ts
@@ -2,35 +2,22 @@ import { run } from "@deepagent-code/tui"
 import { TuiConfig } from "@deepagent-code/tui/config"
 import { Effect } from "effect"
 import { Global } from "@deepagent-code/core/global"
+import { gracefulFetch } from "./services/graceful-fetch"
 
-export function runTui(transport: { url: string; headers: RequestInit["headers"] }) {
+export function runTui(transport: {
+  url: string
+  headers: RequestInit["headers"]
+  fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
+}) {
   const config = TuiConfig.resolve({}, { terminalSuspend: false })
   return run({
     ...transport,
     args: {},
     config,
-    fetch: gracefulFetch,
+    fetch: gracefulFetch(transport.fetch ?? fetch),
     pluginHost: {
       async start() {},
       async dispose() {},
     },
   }).pipe(Effect.provide(Global.defaultLayer))
 }
-
-const legacyDefaults: Record<string, unknown> = {
-  "/config/providers": { providers: [], default: {} },
-  "/provider": { all: [], default: {}, connected: [] },
-  "/agent": [],
-  "/config": {},
-}
-
-const gracefulFetch = Object.assign(
-  async (input: RequestInfo | URL, init?: RequestInit) => {
-    const response = await fetch(input, init)
-    if (response.status !== 404) return response
-    const fallback = legacyDefaults[new URL(input instanceof Request ? input.url : input).pathname]
-    if (fallback === undefined) return response
-    return Response.json(fallback)
-  },
-  { preconnect: fetch.preconnect },
-)
diff --git a/packages/cli/test/connection.test.ts b/packages/cli/test/connection.test.ts
new file mode 100644
index 00000000..e95fc1e8
--- /dev/null
+++ b/packages/cli/test/connection.test.ts
@@ -0,0 +1,121 @@
+import { afterAll, beforeEach, describe, expect, it } from "bun:test"
+import { Effect, Layer, Result } from "effect"
+import * as NodeServices from "@effect/platform-node/NodeServices"
+import { mkdtemp, rm } from "fs/promises"
+import { tmpdir } from "os"
+import path from "path"
+import { Connection } from "../src/services/connection"
+import { Daemon } from "../src/services/daemon"
+import { ServerMode } from "../src/services/server-mode"
+
+// Minimal gateway: login + one-container-per-user endpoints (the full contract
+// is covered by test/server-mode.test.ts).
+const server = Bun.serve({
+  port: 0,
+  async fetch(req) {
+    const url = new URL(req.url)
+    if (url.pathname === "/control/v1/auth/login" && req.method === "POST") {
+      return Response.json(
+        { accessToken: "tok", user: { id: "u-1" } },
+        { headers: { "set-cookie": "refresh_token=ref; HttpOnly; Path=/" } },
+      )
+    }
+    if (url.pathname === "/control/v1/containers") {
+      return Response.json({ id: "ctr-1", status: "running" })
+    }
+    return Response.json({ error: { message: "not found" } }, { status: 404 })
+  },
+})
+const base = `http://127.0.0.1:${server.port}`
+
+// The daemon is stubbed at the service boundary (booting the real one spawns a
+// process). The sentinel URL and call count prove which transport won.
+const daemon = { calls: 0 }
+const daemonLayer = Layer.succeed(
+  Daemon.Service,
+  Daemon.Service.of({
+    client: () => Effect.die("unused"),
+    transport: () =>
+      Effect.sync(() => {
+        daemon.calls++
+        return { url: "daemon://local", headers: {} }
+      }),
+    start: () => Effect.die("unused"),
+    status: () => Effect.succeed(undefined),
+    stop: () => Effect.void,
+    password: () => Effect.die("unused"),
+    register: () => Effect.die("unused"),
+  }),
+)
+
+const run = <A, E>(effect: Effect.Effect<A, E, Connection.Service | ServerMode.Service>) =>
+  Effect.runPromise(
+    effect.pipe(
+      Effect.provide(Connection.defaultLayer),
+      Effect.provide(ServerMode.defaultLayer),
+      Effect.provide(daemonLayer),
+      Effect.provide(NodeServices.layer),
+      Effect.scoped,
+    ),
+  )
+
+const transport = Effect.flatMap(Connection.Service, (connection) => connection.transport())
+
+const login = Effect.fnUntraced(function* (selectWorkspace: boolean) {
+  const serverMode = yield* ServerMode.Service
+  yield* serverMode.login(base, "a@b.c", "pw")
+  if (selectWorkspace) yield* serverMode.useWorkspace("ctr-1")
+})
+
+let home: string
+const homes: string[] = []
+
+beforeEach(async () => {
+  home = await mkdtemp(path.join(tmpdir(), "dacode-cli-test-"))
+  homes.push(home)
+  process.env.DEEPAGENT_CODE_HOME = home
+  delete process.env.DEEPAGENT_GATEWAY_URL
+  daemon.calls = 0
+})
+
+afterAll(async () => {
+  delete process.env.DEEPAGENT_CODE_HOME
+  server.stop()
+  await Promise.all(homes.map((dir) => rm(dir, { recursive: true, force: true })))
+})
+
+describe("Connection.transport", () => {
+  it("falls back to the local daemon when server mode is not active", async () => {
+    const result = await run(transport)
+    expect(result.url).toBe("daemon://local")
+    expect(daemon.calls).toBe(1)
+  })
+
+  it("prefers the server-mode gateway once logged in with a workspace selected", async () => {
+    const result = await run(login(true).pipe(Effect.andThen(transport)))
+    expect(result.url).toBe(`${base}/w`)
+    expect(daemon.calls).toBe(0)
+  })
+
+  it("fails fast with a workspace hint instead of silently falling back when no workspace is selected", async () => {
+    const result = await run(login(false).pipe(Effect.andThen(transport), Effect.result))
+    expect(Result.isFailure(result)).toBe(true)
+    if (Result.isFailure(result)) expect(String(result.failure)).toContain("No workspace selected")
+    expect(daemon.calls).toBe(0)
+  })
+
+  it("warns and falls back to the daemon when the pinned gateway has no matching login", async () => {
+    process.env.DEEPAGENT_GATEWAY_URL = base
+    const written: string[] = []
+    const original = process.stderr.write
+    process.stderr.write = ((chunk: unknown) => (written.push(String(chunk)), true)) as typeof process.stderr.write
+    try {
+      const result = await run(transport)
+      expect(result.url).toBe("daemon://local")
+      expect(daemon.calls).toBe(1)
+      expect(written.join("")).toContain("Falling back to the local daemon")
+    } finally {
+      process.stderr.write = original
+    }
+  })
+})
diff --git a/packages/cli/test/graceful-fetch.test.ts b/packages/cli/test/graceful-fetch.test.ts
new file mode 100644
index 00000000..5f4655e0
--- /dev/null
+++ b/packages/cli/test/graceful-fetch.test.ts
@@ -0,0 +1,61 @@
+import { describe, expect, it } from "bun:test"
+import { gracefulFetch } from "../src/services/graceful-fetch"
+
+describe("gracefulFetch", () => {
+  it("passes non-404 responses through untouched", async () => {
+    const base = async () => Response.json({ ok: true })
+    const response = await gracefulFetch(base)("http://localhost/config")
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({ ok: true })
+  })
+
+  it("answers 404s on legacy config endpoints with empty defaults", async () => {
+    const base = async () => new Response(null, { status: 404 })
+    const fetcher = gracefulFetch(base)
+    expect(await (await fetcher("http://localhost/config")).json()).toEqual({})
+    expect(await (await fetcher("http://localhost/agent")).json()).toEqual([])
+    expect(await (await fetcher("http://localhost/config/providers")).json()).toEqual({
+      providers: [],
+      default: {},
+    })
+  })
+
+  it("returns the original 404 for paths without a legacy default", async () => {
+    const base = async () => new Response("nope", { status: 404 })
+    const response = await gracefulFetch(base)("http://localhost/session")
+    expect(response.status).toBe(404)
+    expect(await response.text()).toBe("nope")
+  })
+
+  it("resolves the URL when the input is a Request object", async () => {
+    const base = async () => new Response(null, { status: 404 })
+    const response = await gracefulFetch(base)(new Request("http://localhost/provider"))
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({ all: [], default: {}, connected: [] })
+  })
+
+  it("matches legacy endpoints under the server-mode /w proxy prefix", async () => {
+    const base = async () => new Response(null, { status: 404 })
+    const fetcher = gracefulFetch(base)
+    expect(await (await fetcher("http://gateway/w/config")).json()).toEqual({})
+    expect(await (await fetcher("http://gateway/w/agent")).json()).toEqual([])
+    expect(await (await fetcher("http://gateway/w/config/providers")).json()).toEqual({
+      providers: [],
+      default: {},
+    })
+  })
+
+  it("delegates to the injected base fetch — the server-mode transport seam", async () => {
+    const seen: string[] = []
+    const base = async (input: RequestInfo | URL) => {
+      seen.push(new URL(input instanceof Request ? input.url : input).pathname)
+      return Response.json({ proxied: true })
+    }
+    const fetcher = gracefulFetch(base)
+    const response = await fetcher("http://gateway/w/session", { method: "POST" })
+    expect(seen).toEqual(["/w/session"])
+    expect(await response.json()).toEqual({ proxied: true })
+    // Bun's preconnect hint is preserved on the wrapper
+    expect(fetcher.preconnect).toBe(fetch.preconnect)
+  })
+})
diff --git a/packages/cli/test/handlers.test.ts b/packages/cli/test/handlers.test.ts
new file mode 100644
index 00000000..ca13fb29
--- /dev/null
+++ b/packages/cli/test/handlers.test.ts
@@ -0,0 +1,145 @@
+import { afterAll, beforeEach, describe, expect, it } from "bun:test"
+import { Effect, Option, Result } from "effect"
+import * as NodeServices from "@effect/platform-node/NodeServices"
+import { mkdtemp, readFile, rm } from "fs/promises"
+import { tmpdir } from "os"
+import path from "path"
+import { ServerMode } from "../src/services/server-mode"
+import login from "../src/commands/handlers/login"
+import logout from "../src/commands/handlers/logout"
+import workspaceList from "../src/commands/handlers/workspace/list"
+import workspaceUse from "../src/commands/handlers/workspace/use"
+
+// Same gateway contract as test/server-mode.test.ts: camelCase accessToken in
+// the body, refresh token as HttpOnly cookie, one container per user.
+const server = Bun.serve({
+  port: 0,
+  async fetch(req) {
+    const url = new URL(req.url)
+    if (url.pathname === "/control/v1/auth/login" && req.method === "POST") {
+      const body = (await req.json()) as { password?: string }
+      if (body.password !== "pw") {
+        return Response.json({ error: { message: "bad credentials" } }, { status: 401 })
+      }
+      return Response.json(
+        { accessToken: "tok", user: { id: "u-1" } },
+        { headers: { "set-cookie": "refresh_token=ref; HttpOnly; Path=/" } },
+      )
+    }
+    if (url.pathname === "/control/v1/containers") {
+      return Response.json({ id: "ctr-1", status: "running" })
+    }
+    if (url.pathname === "/control/v1/auth/logout" && req.method === "POST") {
+      return new Response(null, { status: 204 })
+    }
+    return Response.json({ error: { message: "not found" } }, { status: 404 })
+  },
+})
+const base = `http://127.0.0.1:${server.port}`
+
+const run = <A, E>(effect: Effect.Effect<A, E, ServerMode.Service>) =>
+  Effect.runPromise(
+    effect.pipe(Effect.provide(ServerMode.defaultLayer), Effect.provide(NodeServices.layer), Effect.scoped),
+  )
+
+const capture = async <A>(fn: () => Promise<A>) => {
+  const chunks: string[] = []
+  const original = process.stdout.write
+  process.stdout.write = ((chunk: string | Uint8Array) => {
+    chunks.push(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8"))
+    return true
+  }) as typeof process.stdout.write
+  try {
+    return { value: await fn(), output: chunks.join("") }
+  } finally {
+    process.stdout.write = original
+  }
+}
+
+let home: string
+const homes: string[] = []
+
+beforeEach(async () => {
+  home = await mkdtemp(path.join(tmpdir(), "dacode-cli-test-"))
+  homes.push(home)
+  process.env.DEEPAGENT_CODE_HOME = home
+  delete process.env.DEEPAGENT_GATEWAY_URL
+})
+
+afterAll(async () => {
+  delete process.env.DEEPAGENT_CODE_HOME
+  server.stop()
+  await Promise.all(homes.map((dir) => rm(dir, { recursive: true, force: true })))
+})
+
+const stateFile = () => path.join(home, "state", "server-mode.json")
+
+const credentials = {
+  gateway: Option.some(base),
+  email: Option.some("a@b.c"),
+  password: Option.some("pw"),
+}
+
+describe("login handler", () => {
+  it("logs in with flag-provided credentials and points at workspace selection next", async () => {
+    const { output } = await capture(() => run(login(credentials)))
+    expect(output).toContain(`Logged in to ${base} as a@b.c.`)
+    expect(output).toContain("dacode workspace list")
+    expect(JSON.parse(await readFile(stateFile(), "utf8")).accessToken).toBe("tok")
+  })
+
+  it("fails with a clear message when neither the argument nor DEEPAGENT_GATEWAY_URL is set", async () => {
+    const result = await run(
+      login({ gateway: Option.none(), email: Option.some("a@b.c"), password: Option.some("pw") }).pipe(
+        Effect.result,
+      ),
+    )
+    expect(Result.isFailure(result)).toBe(true)
+    if (Result.isFailure(result)) expect(String(result.failure)).toContain("Gateway URL required")
+  })
+
+  it("falls back to DEEPAGENT_GATEWAY_URL for the gateway argument", async () => {
+    process.env.DEEPAGENT_GATEWAY_URL = `${base}/`
+    const { output } = await capture(() =>
+      run(login({ gateway: Option.none(), email: Option.some("a@b.c"), password: Option.some("pw") })),
+    )
+    expect(output).toContain(`Logged in to ${base} as a@b.c.`)
+  })
+})
+
+describe("logout handler", () => {
+  it("drops the stored server-mode state", async () => {
+    await run(login(credentials))
+    const { output } = await capture(() => run(logout({})))
+    expect(output).toContain("Logged out.")
+    const status = await run(Effect.flatMap(ServerMode.Service, (serverMode) => serverMode.status()))
+    expect(Option.isNone(status)).toBe(true)
+  })
+})
+
+describe("workspace handlers", () => {
+  it("list shows the container, use persists and marks the selection", async () => {
+    await run(login(credentials))
+
+    const before = await capture(() => run(workspaceList({})))
+    expect(before.output).toContain("  ctr-1")
+    expect(before.output).not.toContain("* ctr-1")
+
+    const used = await capture(() => run(workspaceUse({ id: "ctr-1" })))
+    expect(used.output).toContain("Using workspace ctr-1.")
+    expect(JSON.parse(await readFile(stateFile(), "utf8")).workspaceId).toBe("ctr-1")
+
+    const after = await capture(() => run(workspaceList({})))
+    expect(after.output).toContain("* ctr-1")
+  })
+
+  it("use rejects an unknown workspace id with a list hint", async () => {
+    await run(login(credentials))
+    const result = await run(workspaceUse({ id: "ctr-bad" }).pipe(Effect.result))
+    expect(Result.isFailure(result)).toBe(true)
+    if (Result.isFailure(result)) {
+      expect(String(result.failure)).toContain("ctr-bad")
+      expect(String(result.failure)).toContain("dacode workspace list")
+    }
+  })
+})
diff --git a/packages/cli/test/server-mode.test.ts b/packages/cli/test/server-mode.test.ts
new file mode 100644
index 00000000..91e1257e
--- /dev/null
+++ b/packages/cli/test/server-mode.test.ts
@@ -0,0 +1,364 @@
+import { afterAll, beforeEach, describe, expect, it } from "bun:test"
+import { Effect, Option, Result } from "effect"
+import * as NodeServices from "@effect/platform-node/NodeServices"
+import { mkdtemp, readFile, rm, stat, writeFile } from "fs/promises"
+import { tmpdir } from "os"
+import path from "path"
+import { ServerMode } from "../src/services/server-mode"
+
+// Behavior-controllable mock of the Server Edition gateway, matching the
+// contract verified against deepagent-server (see packages/app/src/utils/gateway-client.ts):
+//   - login returns camelCase { accessToken, user } + Set-Cookie refresh_token
+//   - refresh reads the refresh_token cookie and returns { accessToken }
+//   - one container per user: GET /control/v1/containers (200 object | 404),
+//     POST /control/v1/containers provisions it (200 exists | 202 creating)
+//   - data-plane proxy base is a bare /w, located by JWT
+const gateway = {
+  validAccess: "tok-1",
+  refreshCalls: 0,
+  provisioned: true,
+  sessionBodies: [] as string[],
+}
+
+const container = () => ({ id: "ctr-1", userId: "u-1", status: "running", imageVersion: "v1", createdAt: 0 })
+
+const server = Bun.serve({
+  port: 0,
+  async fetch(req) {
+    const url = new URL(req.url)
+    const auth = req.headers.get("authorization")
+    const cookie = req.headers.get("cookie")
+
+    if (url.pathname === "/control/v1/auth/login" && req.method === "POST") {
+      const body = (await req.json()) as { email?: string; password?: string }
+      if (body.password !== "pw") {
+        return Response.json({ error: { code: "UNAUTHORIZED", message: "bad credentials" } }, { status: 401 })
+      }
+      gateway.validAccess = "tok-1"
+      if (body.email === "body@x.y") {
+        // Tolerated legacy shape: refresh token in the JSON body, no cookie.
+        return Response.json({ accessToken: "tok-1", refresh_token: "ref-body", user: { id: "u-1" } })
+      }
+      return Response.json(
+        { accessToken: "tok-1", user: { id: "u-1", email: body.email, role: "user", orgId: "o-1" } },
+        { headers: { "set-cookie": "refresh_token=ref-1; HttpOnly; Path=/" } },
+      )
+    }
+
+    if (url.pathname === "/control/v1/auth/refresh" && req.method === "POST") {
+      gateway.refreshCalls++
+      if (auth === "Bearer ref-1" || cookie?.includes("refresh_token=ref-1")) {
+        gateway.validAccess = "tok-2"
+        return Response.json(
+          { accessToken: "tok-2" },
+          { headers: { "set-cookie": "refresh_token=ref-2; HttpOnly; Path=/" } },
+        )
+      }
+      return Response.json({ error: { code: "UNAUTHORIZED", message: "invalid refresh token" } }, { status: 401 })
+    }
+
+    if (url.pathname === "/control/v1/containers") {
+      if (auth !== `Bearer ${gateway.validAccess}`) {
+        return Response.json({ error: { code: "UNAUTHORIZED", message: "stale token" } }, { status: 401 })
+      }
+      if (req.method === "GET") {
+        if (!gateway.provisioned) {
+          return Response.json({ error: { code: "CONTAINER_NOT_FOUND", message: "no container" } }, { status: 404 })
+        }
+        return Response.json(container())
+      }
+      if (req.method === "POST") {
+        const existed = gateway.provisioned
+        gateway.provisioned = true
+        return Response.json(
+          existed ? container() : { ...container(), status: "creating" },
+          { status: existed ? 200 : 202 },
+        )
+      }
+    }
+
+    if (url.pathname === "/control/v1/auth/logout" && req.method === "POST") {
+      return new Response(null, { status: 204 })
+    }
+
+    if (url.pathname === "/w/ping" && req.method === "GET") {
+      if (auth !== `Bearer ${gateway.validAccess}`) {
+        return Response.json({ error: { code: "UNAUTHORIZED", message: "stale token" } }, { status: 401 })
+      }
+      return Response.json({ ok: true })
+    }
+
+    if (url.pathname === "/w/session" && req.method === "POST") {
+      gateway.sessionBodies.push(await req.text())
+      if (auth !== `Bearer ${gateway.validAccess}`) {
+        return Response.json({ error: { code: "UNAUTHORIZED", message: "stale token" } }, { status: 401 })
+      }
+      return Response.json({ ok: true })
+    }
+
+    return Response.json({ error: { code: "NOT_FOUND", message: "not found" } }, { status: 404 })
+  },
+})
+
+const base = `http://127.0.0.1:${server.port}`
+
+const run = <A, E>(effect: Effect.Effect<A, E, ServerMode.Service>) =>
+  Effect.runPromise(
+    effect.pipe(Effect.provide(ServerMode.defaultLayer), Effect.provide(NodeServices.layer), Effect.scoped),
+  )
+
+const service = Effect.gen(function* () {
+  return yield* ServerMode.Service
+})
+
+let home: string
+const homes: string[] = []
+
+beforeEach(async () => {
+  home = await mkdtemp(path.join(tmpdir(), "dacode-cli-test-"))
+  homes.push(home)
+  process.env.DEEPAGENT_CODE_HOME = home
+  delete process.env.DEEPAGENT_GATEWAY_URL
+  gateway.validAccess = "tok-1"
+  gateway.refreshCalls = 0
+  gateway.provisioned = true
+  gateway.sessionBodies = []
+})
+
+afterAll(async () => {
+  delete process.env.DEEPAGENT_CODE_HOME
+  server.stop()
+  await Promise.all(homes.map((dir) => rm(dir, { recursive: true, force: true })))
+})
+
+const stateFile = () => path.join(home, "state", "server-mode.json")
+
+describe("ServerMode.login", () => {
+  it("stores state with 0600 permissions, the camelCase access token, and the cookie refresh token", async () => {
+    const state = await run(service.pipe(Effect.flatMap((s) => s.login(base, "a@b.c", "pw"))))
+
+    expect(state.gatewayUrl).toBe(base)
+    expect(state.accessToken).toBe("tok-1")
+    expect(state.refreshToken).toBe("ref-1")
+
+    const info = await stat(stateFile())
+    expect(info.mode & 0o777).toBe(0o600)
+    const persisted = JSON.parse(await readFile(stateFile(), "utf8"))
+    expect(persisted.accessToken).toBe("tok-1")
+    expect(persisted.refreshToken).toBe("ref-1")
+  })
+
+  it("falls back to a refresh token in the response body when no cookie is set", async () => {
+    const state = await run(service.pipe(Effect.flatMap((s) => s.login(base, "body@x.y", "pw"))))
+    expect(state.accessToken).toBe("tok-1")
+    expect(state.refreshToken).toBe("ref-body")
+  })
+
+  it("fails with the gateway error message on bad credentials", async () => {
+    const result = await run(service.pipe(Effect.flatMap((s) => s.login(base, "a@b.c", "nope")), Effect.result))
+    expect(Result.isFailure(result)).toBe(true)
+    if (Result.isFailure(result)) expect(String(result.failure)).toContain("bad credentials")
+  })
+
+  it("keeps the selected workspace when re-logging into the same gateway", async () => {
+    const state = await run(
+      service.pipe(
+        Effect.flatMap((s) => s.login(base, "a@b.c", "pw")),
+        Effect.flatMap(() => service),
+        Effect.flatMap((s) => s.useWorkspace("ctr-1")),
+        Effect.flatMap(() => service),
+        Effect.flatMap((s) => s.login(base, "a@b.c", "pw")),
+        Effect.flatMap(() => service),
+        Effect.flatMap((s) => s.status()),
+      ),
+    )
+    expect(Option.isSome(state)).toBe(true)
+    if (Option.isSome(state)) expect(state.value.workspaceId).toBe("ctr-1")
+  })
+})
+
+describe("ServerMode.workspaces", () => {
+  it("refreshes a stale access token and retries once", async () => {
+    const list = await run(
+      service.pipe(
+        Effect.flatMap((s) => s.login(base, "a@b.c", "pw")),
+        // Simulate the gateway having rotated the token server-side
+        Effect.tap(() => Effect.sync(() => (gateway.validAccess = "tok-2"))),
+        Effect.flatMap(() => service),
+        Effect.flatMap((s) => s.workspaces()),
+      ),
+    )
+
+    expect(list).toEqual([{ id: "ctr-1", status: "running" }])
+    expect(gateway.refreshCalls).toBe(1)
+
+    const persisted = JSON.parse(await readFile(stateFile(), "utf8"))
+    expect(persisted.accessToken).toBe("tok-2")
+    expect(persisted.refreshToken).toBe("ref-2")
+  })
+
+  it("provisions the container via POST when GET returns 404", async () => {
+    gateway.provisioned = false
+    const list = await run(
+      service.pipe(
+        Effect.flatMap((s) => s.login(base, "a@b.c", "pw")),
+        Effect.flatMap(() => service),
+        Effect.flatMap((s) => s.workspaces()),
+      ),
+    )
+    expect(list).toEqual([{ id: "ctr-1", status: "creating" }])
+    expect(gateway.provisioned).toBe(true)
+  })
+
+  it("fails with a login hint when DEEPAGENT_GATEWAY_URL pins a different gateway", async () => {
+    const result = await run(
+      service.pipe(
+        Effect.flatMap((s) => s.login(base, "a@b.c", "pw")),
+        Effect.tap(() => Effect.sync(() => (process.env.DEEPAGENT_GATEWAY_URL = "http://127.0.0.1:1"))),
+        Effect.flatMap(() => service),
+        Effect.flatMap((s) => s.workspaces()),
+        Effect.result,
+      ),
+    )
+    expect(Result.isFailure(result)).toBe(true)
+    if (Result.isFailure(result)) expect(String(result.failure)).toContain("Not logged in to http://127.0.0.1:1")
+  })
+
+  it("accepts a pinned DEEPAGENT_GATEWAY_URL with a trailing slash", async () => {
+    const transport = await run(
+      service.pipe(
+        Effect.flatMap((s) => s.login(base, "a@b.c", "pw")),
+        Effect.flatMap(() => service),
+        Effect.flatMap((s) => s.useWorkspace("ctr-1")),
+        Effect.tap(() => Effect.sync(() => (process.env.DEEPAGENT_GATEWAY_URL = `${base}/`))),
+        Effect.flatMap(() => service),
+        Effect.flatMap((s) => s.transport()),
+      ),
+    )
+    expect(Option.isSome(transport)).toBe(true)
+  })
+})
+
+describe("ServerMode.useWorkspace", () => {
+  it("persists the selection and rejects unknown ids", async () => {
+    const found = await run(
+      service.pipe(
+        Effect.flatMap((s) => s.login(base, "a@b.c", "pw")),
+        Effect.flatMap(() => service),
+        Effect.flatMap((s) => s.useWorkspace("ctr-1")),
+      ),
+    )
+    expect(found.id).toBe("ctr-1")
+    expect(JSON.parse(await readFile(stateFile(), "utf8")).workspaceId).toBe("ctr-1")
+
+    const missing = await run(service.pipe(Effect.flatMap((s) => s.useWorkspace("ctr-bad")), Effect.result))
+    expect(Result.isFailure(missing)).toBe(true)
+    if (Result.isFailure(missing)) expect(String(missing.failure)).toContain("ctr-bad")
+  })
+})
+
+describe("ServerMode.transport", () => {
+  it("is none when server mode is not active", async () => {
+    const transport = await run(service.pipe(Effect.flatMap((s) => s.transport())))
+    expect(Option.isNone(transport)).toBe(true)
+  })
+
+  it("targets the bare /w proxy and its fetch injects auth with 401 refresh retry", async () => {
+    const transport = await run(
+      service.pipe(
+        Effect.flatMap((s) => s.login(base, "a@b.c", "pw")),
+        Effect.flatMap(() => service),
+        Effect.flatMap((s) => s.useWorkspace("ctr-1")),
+        Effect.flatMap(() => service),
+        Effect.flatMap((s) => s.transport()),
+      ),
+    )
+    expect(Option.isSome(transport)).toBe(true)
+    if (Option.isNone(transport)) return
+    expect(transport.value.url).toBe(`${base}/w`)
+
+    // Stale token on the wire: the fetch must refresh and retry transparently
+    gateway.validAccess = "tok-2"
+    const response = await transport.value.fetch(`${transport.value.url}/ping`)
+    expect(response.status).toBe(200)
+    expect(gateway.refreshCalls).toBe(1)
+  })
+
+  it("replays a POST Request with a body after a 401 refresh", async () => {
+    const transport = await run(
+      service.pipe(
+        Effect.flatMap((s) => s.login(base, "a@b.c", "pw")),
+        Effect.flatMap(() => service),
+        Effect.flatMap((s) => s.useWorkspace("ctr-1")),
+        Effect.flatMap(() => service),
+        Effect.flatMap((s) => s.transport()),
+      ),
+    )
+    expect(Option.isSome(transport)).toBe(true)
+    if (Option.isNone(transport)) return
+
+    // The SDK passes a single Request object; its body is consumed by the
+    // first attempt, so the retry must replay a clone.
+    gateway.validAccess = "tok-2"
+    const payload = JSON.stringify({ prompt: "hello" })
+    const request = new Request(`${base}/w/session`, {
+      method: "POST",
+      body: payload,
+      headers: { "content-type": "application/json" },
+    })
+    const response = await transport.value.fetch(request)
+    expect(response.status).toBe(200)
+    expect(gateway.refreshCalls).toBe(1)
+    expect(gateway.sessionBodies).toEqual([payload, payload])
+  })
+
+  it("coalesces concurrent 401s into a single refresh", async () => {
+    const transport = await run(
+      service.pipe(
+        Effect.flatMap((s) => s.login(base, "a@b.c", "pw")),
+        Effect.flatMap(() => service),
+        Effect.flatMap((s) => s.useWorkspace("ctr-1")),
+        Effect.flatMap(() => service),
+        Effect.flatMap((s) => s.transport()),
+      ),
+    )
+    expect(Option.isSome(transport)).toBe(true)
+    if (Option.isNone(transport)) return
+
+    gateway.validAccess = "tok-2"
+    const responses = await Promise.all(
+      Array.from({ length: 5 }, () => transport.value.fetch(`${transport.value.url}/ping`)),
+    )
+    expect(responses.map((response) => response.status)).toEqual([200, 200, 200, 200, 200])
+    expect(gateway.refreshCalls).toBe(1)
+  })
+
+  it("surfaces session expiry when the gateway rejects the refresh token", async () => {
+    const transport = await run(
+      service.pipe(
+        Effect.flatMap((s) => s.login(base, "a@b.c", "pw")),
+        Effect.flatMap(() => service),
+        Effect.flatMap((s) => s.useWorkspace("ctr-1")),
+        Effect.flatMap(() => service),
+        Effect.flatMap((s) => s.transport()),
+      ),
+    )
+    expect(Option.isSome(transport)).toBe(true)
+    if (Option.isNone(transport)) return
+
+    // Corrupt the persisted refresh token so the 401 retry cannot recover
+    const persisted = JSON.parse(await readFile(stateFile(), "utf8"))
+    await writeFile(stateFile(), JSON.stringify({ ...persisted, refreshToken: "ref-bad" }))
+    gateway.validAccess = "tok-2"
+    await expect(transport.value.fetch(`${transport.value.url}/ping`)).rejects.toThrow("Session expired")
+    expect(gateway.refreshCalls).toBe(1)
+  })
+
+  it("fails when logged in but no workspace is selected", async () => {
+    const result = await run(
+      service.pipe(Effect.flatMap((s) => s.login(base, "a@b.c", "pw")), Effect.flatMap(() => service), Effect.flatMap((s) => s.transport()), Effect.result),
+    )
+    expect(Result.isFailure(result)).toBe(true)
+    if (Result.isFailure(result)) expect(String(result.failure)).toContain("No workspace selected")
+  })
+})
diff --git a/packages/core/src/flag/flag.ts b/packages/core/src/flag/flag.ts
index 9c209fd4..ff88cbe5 100644
--- a/packages/core/src/flag/flag.ts
+++ b/packages/core/src/flag/flag.ts
@@ -30,6 +30,15 @@ export const Flag = {
   DEEPAGENT_CODE_FAKE_VCS: process.env["DEEPAGENT_CODE_FAKE_VCS"],
   DEEPAGENT_CODE_SERVER_PASSWORD: process.env["DEEPAGENT_CODE_SERVER_PASSWORD"],
   DEEPAGENT_CODE_SERVER_USERNAME: process.env["DEEPAGENT_CODE_SERVER_USERNAME"],
+  // Server Edition: CI injects the deepagent-code commit into workspace images so
+  // the gateway can report/version-check the data plane (server-v1 §13.3).
+  DEEPAGENT_CODE_COMMIT: process.env["DEEPAGENT_CODE_COMMIT"],
+  // Server Edition: when running inside a gateway-managed workspace container,
+  // provider keys are injected via env and must not persist to the volume (§20.4).
+  // Getter so tests can toggle it per-case (matches the experimental-flag pattern).
+  get DEEPAGENT_SERVER_MODE() {
+    return truthy("DEEPAGENT_SERVER_MODE")
+  },
 
   // Experimental
   DEEPAGENT_CODE_EXPERIMENTAL_FILEWATCHER: Config.boolean("DEEPAGENT_CODE_EXPERIMENTAL_FILEWATCHER").pipe(
diff --git a/packages/deepagent-code/package.json b/packages/deepagent-code/package.json
index b3e648fa..a2ebf635 100644
--- a/packages/deepagent-code/package.json
+++ b/packages/deepagent-code/package.json
@@ -21,6 +21,7 @@
     "deepagent": "./bin/deepagent"
   },
   "exports": {
+    "./server": "./src/server/server.ts",
     "./*": "./src/*.ts"
   },
   "imports": {
diff --git a/packages/deepagent-code/src/auth/index.ts b/packages/deepagent-code/src/auth/index.ts
index 2c783957..8bbe0a44 100644
--- a/packages/deepagent-code/src/auth/index.ts
+++ b/packages/deepagent-code/src/auth/index.ts
@@ -2,6 +2,7 @@ import path from "path"
 import { Effect, Layer, Record, Result, Schema, Context } from "effect"
 import { NonNegativeInt } from "@deepagent-code/core/schema"
 import { Global } from "@deepagent-code/core/global"
+import { Flag } from "@deepagent-code/core/flag/flag"
 import { FSUtil } from "@deepagent-code/core/fs-util"
 
 export const OAUTH_DUMMY_KEY = "deepagent-code-oauth-dummy-key"
@@ -70,6 +71,13 @@ export const layer = Layer.effect(
     })
 
     const set = Effect.fn("Auth.set")(function* (key: string, info: Info) {
+      // Server Edition (§20.4): gateway-managed containers receive provider keys
+      // via env injection; persisting them to the workspace volume is forbidden.
+      if (Flag.DEEPAGENT_SERVER_MODE)
+        return yield* new AuthError({
+          message:
+            "Provider credentials are managed by the gateway in server mode; persisting auth.json is disabled (DEEPAGENT_SERVER_MODE)",
+        })
       const norm = key.replace(/\/+$/, "")
       const data = yield* all()
       if (norm !== key) delete data[key]
@@ -80,6 +88,11 @@ export const layer = Layer.effect(
     })
 
     const remove = Effect.fn("Auth.remove")(function* (key: string) {
+      if (Flag.DEEPAGENT_SERVER_MODE)
+        return yield* new AuthError({
+          message:
+            "Provider credentials are managed by the gateway in server mode; modifying auth.json is disabled (DEEPAGENT_SERVER_MODE)",
+        })
       const norm = key.replace(/\/+$/, "")
       const data = yield* all()
       delete data[key]
diff --git a/packages/deepagent-code/src/server/routes/instance/httpapi/groups/global.ts b/packages/deepagent-code/src/server/routes/instance/httpapi/groups/global.ts
index 794513a0..2c9f1deb 100644
--- a/packages/deepagent-code/src/server/routes/instance/httpapi/groups/global.ts
+++ b/packages/deepagent-code/src/server/routes/instance/httpapi/groups/global.ts
@@ -24,6 +24,9 @@ const GlobalHealth = Schema.Struct({
 const GlobalCapabilities = Schema.Struct({
   protocolVersion: Schema.String,
   version: Schema.String,
+  // deepagent-code commit the data plane was built from; only present when CI
+  // injected DEEPAGENT_CODE_COMMIT (workspace images), absent on local builds.
+  commit: Schema.optional(Schema.String),
   features: Schema.Struct({
     im: Schema.Boolean,
     sessions: Schema.Boolean,
diff --git a/packages/deepagent-code/src/server/routes/instance/httpapi/handlers/global.ts b/packages/deepagent-code/src/server/routes/instance/httpapi/handlers/global.ts
index 7c339e35..b3010d79 100644
--- a/packages/deepagent-code/src/server/routes/instance/httpapi/handlers/global.ts
+++ b/packages/deepagent-code/src/server/routes/instance/httpapi/handlers/global.ts
@@ -6,6 +6,7 @@ import { EventV2 } from "@deepagent-code/core/event"
 import { Installation } from "@/installation"
 import { disposeAllInstancesAndEmitGlobalDisposed, disposeInstancesForDirectories } from "@/server/global-lifecycle"
 import { InstallationVersion } from "@deepagent-code/core/installation/version"
+import { Flag } from "@deepagent-code/core/flag/flag"
 import { IM_PROTOCOL_VERSION } from "@deepagent-code/core/im/protocol"
 import * as Log from "@deepagent-code/core/util/log"
 import { Effect, Queue, Schema } from "effect"
@@ -91,6 +92,7 @@ export const globalHandlers = HttpApiBuilder.group(RootHttpApi, "global", (handl
       return {
         protocolVersion: IM_PROTOCOL_VERSION,
         version: InstallationVersion,
+        commit: Flag.DEEPAGENT_CODE_COMMIT,
         features: {
           im: true,
           sessions: true,
diff --git a/packages/deepagent-code/test/auth/auth.test.ts b/packages/deepagent-code/test/auth/auth.test.ts
index e9d2a9ce..ac69c44a 100644
--- a/packages/deepagent-code/test/auth/auth.test.ts
+++ b/packages/deepagent-code/test/auth/auth.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect } from "bun:test"
-import { Effect, Layer } from "effect"
+import { Effect, Layer, Result } from "effect"
 import { Auth } from "../../src/auth"
 import { CrossSpawnSpawner } from "@deepagent-code/core/cross-spawn-spawner"
 import { testEffect } from "../lib/effect"
@@ -75,3 +75,32 @@ describe("Auth", () => {
     }),
   )
 })
+
+describe("Auth server mode (DEEPAGENT_SERVER_MODE, server-v1 §20.4)", () => {
+  it.instance("set/remove fail closed while the flag is on, and recover when off", () =>
+    Effect.gen(function* () {
+      const auth = yield* Auth.Service
+      process.env.DEEPAGENT_SERVER_MODE = "true"
+      try {
+        const set = yield* auth.set("openai", { type: "api", key: "sk-test" }).pipe(Effect.result)
+        expect(Result.isFailure(set)).toBe(true)
+        if (Result.isFailure(set)) {
+          expect(set.failure._tag).toBe("AuthError")
+          expect(set.failure.message).toContain("server mode")
+        }
+        const remove = yield* auth.remove("openai").pipe(Effect.result)
+        expect(Result.isFailure(remove)).toBe(true)
+        // Blocked writes must not have persisted anything
+        const data = yield* auth.all()
+        expect(data["openai"]).toBeUndefined()
+      } finally {
+        delete process.env.DEEPAGENT_SERVER_MODE
+      }
+      // Flag off again: writes work (guards against process-global flag leakage)
+      yield* auth.set("openai", { type: "api", key: "sk-test" })
+      const data = yield* auth.all()
+      expect(data["openai"]).toBeDefined()
+      yield* auth.remove("openai")
+    }),
+  )
+})

From 2c36aea9bfa24bc59cf2c34bf88ab0bf593d7c01 Mon Sep 17 00:00:00 2001
From: deepagent-ai <jamessmithm539@gmail.com>
Date: Thu, 23 Jul 2026 10:24:19 +0800
Subject: [PATCH 5/5] =?UTF-8?q?fix(audit):=20durable=20consumer=20lifecycl?=
 =?UTF-8?q?e,=20tab=20restore,=20steer=20multipart,=E2=80=A6=20(#85)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

… task pagination and interruption UI

Audit P1/P2 fixes from review:
- V4 durable consumer group register/unregister lifecycle with cleanup
on flag change
- task interrupted state recognized in UI (state:interrupted + legacy
boolean compat)
- task_read cursor pushed to MessageV2.page for proper pagination beyond
101 messages
- server-aware tab restore persists active tab key, not store[0]
ordering
- busy steer preserves all prompt parts (file/image/agent) with
server-minted canonical ID
- steer correlationID idempotency: same payload returns stored row,
different payload returns 409
- terminal host close routing: side panel closes rightPanel not bottom
dock
- terminal lifecycle race: closeRequest gates before auto-create to
prevent restart

### Issue for this PR

Closes #

### Type of change

- [ ] Bug fix
- [ ] New feature
- [ ] Refactor / code improvement
- [ ] Documentation

### What does this PR do?

Please provide a description of the issue, the changes you made to fix
it, and why they work. It is expected that you understand why your
changes work and if you do not understand why at least say as much so a
maintainer knows how much to value the PR.

**If you paste a large clearly AI generated description here your PR may
be IGNORED or CLOSED!**

### How did you verify your code works?

### Screenshots / recordings

_If this is a UI change, please include a screenshot or recording._

### Checklist

- [ ] I have tested my changes locally
- [ ] I have not included unrelated changes in this PR

_If you do not follow this template your PR will be automatically
rejected._

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
---
 packages/app/src/app.tsx                      |  20 +-
 packages/app/src/components/terminal.tsx      |  29 +++
 packages/app/src/context/layout.tsx           |   5 +
 packages/app/src/context/tabs.test.ts         |  38 ++++
 packages/app/src/context/tabs.tsx             |  26 ++-
 packages/app/src/context/terminal.tsx         |  61 +++++-
 .../src/pages/session/session-side-panel.tsx  |   7 +-
 .../pages/session/side-panel-subagents.tsx    |   7 +-
 .../src/pages/session/subagent-state.test.ts  |  10 +
 .../app/src/pages/session/subagent-state.ts   |  10 +
 .../app/src/pages/session/terminal-view.tsx   |   1 +
 packages/core/src/database/migration.gen.ts   |   1 +
 ...0260722000000_session_steer_correlation.ts |  16 ++
 packages/core/src/session/sql.ts              |   5 +
 packages/deepagent-code/src/session/prompt.ts | 188 +++++++++++-------
 packages/deepagent-code/src/session/steer.ts  |  47 +++--
 .../src/session/v4-event-runtime.ts           |  48 ++++-
 packages/deepagent-code/src/tool/task_read.ts |  38 ++--
 .../deepagent-code/test/session/steer.test.ts |  25 +--
 .../test/session/v4-event-runtime.test.ts     |  84 +++++++-
 .../test/tool/task-read.test.ts               | 107 ++++++++++
 21 files changed, 626 insertions(+), 147 deletions(-)
 create mode 100644 packages/app/src/context/tabs.test.ts
 create mode 100644 packages/app/src/pages/session/subagent-state.test.ts
 create mode 100644 packages/app/src/pages/session/subagent-state.ts
 create mode 100644 packages/core/src/database/migration/20260722000000_session_steer_correlation.ts
 create mode 100644 packages/deepagent-code/test/tool/task-read.test.ts

diff --git a/packages/app/src/app.tsx b/packages/app/src/app.tsx
index 7acbad26..0da7afc6 100644
--- a/packages/app/src/app.tsx
+++ b/packages/app/src/app.tsx
@@ -45,7 +45,7 @@ import { PromptProvider } from "@/context/prompt"
 import { ServerConnection, ServerProvider, serverName, useServer } from "@/context/server"
 import { SettingsProvider } from "@/context/settings"
 import { TerminalProvider } from "@/context/terminal"
-import { TabsProvider, useTabs } from "@/context/tabs"
+import { startupTab, TabsProvider, useTabs } from "@/context/tabs"
 import { WslServersProvider } from "@/wsl/context"
 import DirectoryLayout from "@/pages/directory-layout"
 import Layout from "@/pages/layout"
@@ -144,20 +144,22 @@ function SessionProviders(props: ParentProps) {
 
 function RouterRoot(props: ParentProps<{ appChildren?: JSX.Element }>) {
   const tabs = useTabs()
+  const server = useServer()
   const navigate = useNavigate()
   const location = useLocation()
 
-  // On startup: as soon as persisted tabs are loaded (local disk, no HTTP calls),
-  // navigate to the last visited project's session list. This matches opencode's approach —
-  // use local/cached data to drive the first frame, let the server data fill in asynchronously.
-  // We navigate to /:dir/session (no specific session ID) so autoselecting can handle
-  // the final session selection independently without conflicting navigation.
+  // Restore the explicitly persisted active tab. A cross-server directory is never
+  // navigated until the target server has become active.
   createEffect(() => {
     if (!tabs.ready()) return
     if (location.pathname !== "/") return
-    const first = tabs.store[0]
-    if (!first) return
-    navigate(`/${first.dirBase64}/session`, { replace: true })
+    const tab = startupTab(tabs.store, tabs.active.key, server.list)
+    if (!tab) return
+    if (server.key !== tab.server) {
+      server.setActive(tab.server)
+      return
+    }
+    navigate(`/${tab.dirBase64}/session`, { replace: true })
   })
 
   return (
diff --git a/packages/app/src/components/terminal.tsx b/packages/app/src/components/terminal.tsx
index 8897c050..ef79fd36 100644
--- a/packages/app/src/components/terminal.tsx
+++ b/packages/app/src/components/terminal.tsx
@@ -35,6 +35,10 @@ export interface TerminalProps extends ComponentProps<"div"> {
   runtimeId?: string
   onSubmit?: () => void
   onStatusChange?: (status: TerminalStatus, error?: TerminalFailure) => void
+  /** When true (restored PTY), show the terminal immediately after xterm initialises
+   *  instead of waiting for the WebSocket handshake. The WebSocket still connects in
+   *  the background; input typed before it's ready is buffered. */
+  optimisticReady?: boolean
 }
 
 let shared: Promise<{ mod: typeof import("ghostty-web"); ghostty: Ghostty }> | undefined
@@ -159,6 +163,7 @@ export const Terminal = (props: TerminalProps) => {
     "runtimeId",
     "onSubmit",
     "onStatusChange",
+    "optimisticReady",
   ])
   const id = local.pty.ptyId
   let ws: WebSocket | undefined
@@ -435,6 +440,8 @@ export const Terminal = (props: TerminalProps) => {
       })
       cleanups.push(() => disposeIfDisposable(onResize))
       const onData = t.onData((data) => {
+        // When optimisticReady is active the buffering handler below takes over.
+        if (local.optimisticReady) return
         if (ws?.readyState === WebSocket.OPEN) ws.send(data)
       })
       cleanups.push(() => disposeIfDisposable(onData))
@@ -456,6 +463,28 @@ export const Terminal = (props: TerminalProps) => {
       scheduleSize(t.cols, t.rows)
       startResize()
 
+      // For restored PTYs: show the terminal surface immediately after xterm is
+      // initialised instead of waiting for the full WebSocket handshake (which can
+      // take 2-4 s). Input typed before the socket opens is buffered and flushed
+      // once the connection is established.
+      let inputBuffer = local.optimisticReady ? "" : undefined
+      if (local.optimisticReady) {
+        markReady()
+        // Intercept onData to buffer keystrokes until the WebSocket is open.
+        const onDataOpt = t.onData((data) => {
+          if (ws?.readyState === WebSocket.OPEN) {
+            if (inputBuffer) {
+              ws.send(inputBuffer)
+              inputBuffer = undefined
+            }
+            ws.send(data)
+          } else {
+            inputBuffer = (inputBuffer ?? "") + data
+          }
+        })
+        cleanups.push(() => disposeIfDisposable(onDataOpt))
+      }
+
       const once = { value: false }
       const decoder = new TextDecoder()
 
diff --git a/packages/app/src/context/layout.tsx b/packages/app/src/context/layout.tsx
index fca1b7b4..9c296052 100644
--- a/packages/app/src/context/layout.tsx
+++ b/packages/app/src/context/layout.tsx
@@ -938,6 +938,11 @@ export const { use: useLayout, provider: LayoutProvider } = createSimpleContext(
           const session = key()
           const current = store.sessionView[session]
           const bottom = next.bottomPanel
+          // Keep the project-level terminal flag in sync so that switching to a
+          // session that has never explicitly opened the panel doesn't close it.
+          // `bottomPanel` memo falls back to `store.terminal?.opened` for new
+          // sessions — this makes that fallback reflect the current user intent.
+          setTerminalOpened(bottom?.opened === true && bottom?.activeView === "terminal")
           if (!current) {
             setStore("sessionView", session, { scroll: {}, bottomPanel: bottom, rightPanelMode: next.rightPanelMode })
             return
diff --git a/packages/app/src/context/tabs.test.ts b/packages/app/src/context/tabs.test.ts
new file mode 100644
index 00000000..de8e7de2
--- /dev/null
+++ b/packages/app/src/context/tabs.test.ts
@@ -0,0 +1,38 @@
+import { describe, expect, test } from "bun:test"
+import { ServerConnection } from "./server"
+import { startupTab, tabKey, type Tab } from "./tabs"
+
+const primary = ServerConnection.Key.make("http://primary")
+const secondary = ServerConnection.Key.make("http://secondary")
+
+const servers = [
+  { type: "http" as const, http: { url: "http://primary" } },
+  { type: "http" as const, http: { url: "http://secondary" } },
+]
+
+const first: Tab = {
+  type: "session",
+  server: primary,
+  dirBase64: "L3ByaW1hcnk=",
+  sessionId: "first",
+}
+const lastActive: Tab = {
+  type: "session",
+  server: secondary,
+  dirBase64: "L3NlY29uZGFyeQ==",
+  sessionId: "last-active",
+}
+
+describe("startup tab recovery", () => {
+  test("restores the persisted active tab rather than the first tab", () => {
+    expect(startupTab([first, lastActive], tabKey(lastActive), servers)).toBe(lastActive)
+  })
+
+  test("falls back to the first stored tab when the active key is stale", () => {
+    expect(startupTab([first, lastActive], "stale", servers)).toBe(first)
+  })
+
+  test("does not restore a target whose server is unavailable", () => {
+    expect(startupTab([first, lastActive], tabKey(lastActive), [servers[0]])).toBeUndefined()
+  })
+})
diff --git a/packages/app/src/context/tabs.tsx b/packages/app/src/context/tabs.tsx
index 517d4057..64ac3e46 100644
--- a/packages/app/src/context/tabs.tsx
+++ b/packages/app/src/context/tabs.tsx
@@ -20,6 +20,16 @@ export type Tab = SessionTab
 export const tabHref = (tab: Tab) => `/${tab.dirBase64}/session/${tab.sessionId}`
 export const tabKey = (tab: Tab) => `${tab.server}\n${tabHref(tab)}`
 
+export function activeTab(tabs: Tab[], key?: string) {
+  return tabs.find((tab) => tabKey(tab) === key) ?? tabs[0]
+}
+
+export function startupTab(tabs: Tab[], activeKey: string | undefined, servers: ServerConnection.Any[]) {
+  const tab = activeTab(tabs, activeKey)
+  if (!tab) return
+  return servers.some((server) => ServerConnection.key(server) === tab.server) ? tab : undefined
+}
+
 export function sessionHasOpenTab(tabs: Tab[], server: ServerConnection.Key, session: Session) {
   const dirBase64 = base64Encode(session.directory)
   return tabs.some(
@@ -47,6 +57,10 @@ export const { use: useTabs, provider: TabsProvider } = createSimpleContext({
       },
       createStore<Tab[]>([]),
     )
+    const [active, setActive, _activePersist, activeReady] = persisted(
+      Persist.global("tabs.active"),
+      createStore({ key: undefined as string | undefined }),
+    )
 
     const params = useParams()
     const navigate = useNavigate()
@@ -61,6 +75,7 @@ export const { use: useTabs, provider: TabsProvider } = createSimpleContext({
     })
 
     const navigateTab = (tab: Tab) => {
+      setActive("key", tabKey(tab))
       const href = tabHref(tab)
       if (tab.server === server.key) {
         navigate(href)
@@ -96,13 +111,20 @@ export const { use: useTabs, provider: TabsProvider } = createSimpleContext({
             }),
           )
           if (nextTab) navigateTab(nextTab)
-          else navigate("/")
+          else {
+            setActive("key", undefined)
+            navigate("/")
+          }
         }).finally(() => closing.delete(key))
       },
       removeServer(key: ServerConnection.Key) {
         setStore((tabs) => tabs.filter((tab) => tab.server !== key))
+        if (active.key?.startsWith(`${key}\n`)) setActive("key", undefined)
         if (server.key === key) navigate("/")
       },
+      setActive(tab: Tab) {
+        navigateTab(tab)
+      },
       removeSessions: (input: SessionTabsRemovedDetail) => {
         void startTransition(() => {
           setStore(
@@ -145,6 +167,6 @@ export const { use: useTabs, provider: TabsProvider } = createSimpleContext({
       },
     }
 
-    return { ...actions, store, ready }
+    return { ...actions, active, ready: () => ready() && activeReady(), store }
   },
 })
diff --git a/packages/app/src/context/terminal.tsx b/packages/app/src/context/terminal.tsx
index 65c76500..eecaf9a0 100644
--- a/packages/app/src/context/terminal.tsx
+++ b/packages/app/src/context/terminal.tsx
@@ -52,6 +52,8 @@ export type LocalPTY = {
   titleNumber: number
   status: TerminalStatus
   error?: TerminalFailure
+  /** True when restored from cross-project navigation cache; cleared on first ready. */
+  restored?: boolean
 }
 
 export type TerminalStore = {
@@ -313,6 +315,14 @@ function removeTerminalPersistence(
 type TerminalSession = ReturnType<typeof createWorkspaceTerminalSession>
 const sessions = new Set<{ dir: string; scope: ServerScopeValue; value: TerminalSession }>()
 
+/** Per-directory PTY snapshot preserved across project switches so PTYs survive navigation. */
+interface TerminalPtySnapshot {
+  ptys: Array<Pick<LocalPTY, "id" | "ptyId" | "title" | "titleNumber">>
+  root: PaneNode
+  focusedPaneId: string
+}
+const directoryTerminalCache = new Map<string, { bottom: TerminalPtySnapshot | null; side: TerminalPtySnapshot | null }>()
+
 export function clearWorkspaceTerminals(
   dir: string,
   sessionIDs?: string[],
@@ -535,6 +545,37 @@ function createWorkspaceTerminalSession(
     resetRuntime() {
       reset()
     },
+    snapshot(): TerminalPtySnapshot | null {
+      if (store.all.length === 0) return null
+      return {
+        ptys: store.all.map((pty) => ({
+          id: pty.id,
+          ptyId: pty.ptyId,
+          title: pty.title,
+          titleNumber: pty.titleNumber,
+        })),
+        root: root(),
+        focusedPaneId: focusedPaneId(),
+      }
+    },
+    restore(snapshot: TerminalPtySnapshot) {
+      batch(() => {
+        setStore(
+          "all",
+          snapshot.ptys.map((p) => ({
+            id: p.id,
+            ptyId: p.ptyId,
+            title: p.title,
+            titleNumber: p.titleNumber,
+            status: "connecting" as TerminalStatus,
+            error: undefined,
+            restored: true,
+          })),
+        )
+        setRootSignal(clonePaneTree(snapshot.root))
+        setFocusedPaneId(snapshot.focusedPaneId)
+      })
+    },
     clear() {
       const ptyIds = store.all.map((pty) => pty.ptyId)
       reset()
@@ -633,7 +674,7 @@ function createWorkspaceTerminalSession(
     setStatus(id: string, ptyId: string, status: TerminalStatus, error?: TerminalFailure) {
       const index = store.all.findIndex((pty) => pty.id === id && pty.ptyId === ptyId)
       if (index === -1) return
-      setStore("all", index, { status, error: status === "ready" ? undefined : error })
+      setStore("all", index, { status, error: status === "ready" ? undefined : error, ...(status === "ready" ? { restored: false } : {}) })
     },
     update(input: Partial<LocalPTY> & { id: string }) {
       if (input.title === undefined) return
@@ -772,6 +813,16 @@ const { use: useTerminalDual, provider: TerminalProvider } = createSimpleContext
     bottomSession = createWorkspaceTerminalSession(sdk, runtime)
     sideSession = createWorkspaceTerminalSession(sdk, runtime)
 
+    // Restore previously-saved PTYs when returning to a directory.
+    // The cached snapshot was written by onCleanup — PTYs stayed alive on the
+    // server and just need to be re-registered in local reactive state.
+    const cached = directoryTerminalCache.get(sdk.directory)
+    if (cached) {
+      directoryTerminalCache.delete(sdk.directory)
+      if (cached.bottom) bottomSession.restore(cached.bottom)
+      if (cached.side) sideSession.restore(cached.side)
+    }
+
     const bottomReg = { dir: sdk.directory, scope, value: bottomSession }
     const sideReg = { dir: sdk.directory, scope, value: sideSession }
     sessions.add(bottomReg)
@@ -786,10 +837,14 @@ const { use: useTerminalDual, provider: TerminalProvider } = createSimpleContext
       onCleanup(() => clearInterval(timer))
     })
     onCleanup(() => {
+      // Save PTY state so terminals survive project navigation. Do NOT call
+      // clear() here — that would DELETE PTYs on the server. The PTYs keep
+      // running and are reconnected when the user returns to this directory.
+      const bottomSnap = bottomSession?.snapshot() ?? null
+      const sideSnap = sideSession?.snapshot() ?? null
+      directoryTerminalCache.set(sdk.directory, { bottom: bottomSnap, side: sideSnap })
       sessions.delete(bottomReg)
       sessions.delete(sideReg)
-      bottomSession?.clear()
-      sideSession?.clear()
     })
 
     return { bottom: bottomSession, side: sideSession }
diff --git a/packages/app/src/pages/session/session-side-panel.tsx b/packages/app/src/pages/session/session-side-panel.tsx
index ce5bc65d..1262d115 100644
--- a/packages/app/src/pages/session/session-side-panel.tsx
+++ b/packages/app/src/pages/session/session-side-panel.tsx
@@ -23,6 +23,7 @@ import { IdeFileEditor } from "@/pages/session/ide-file-editor"
 import { setSessionHandoff } from "@/pages/session/handoff"
 import { useSessionLayout } from "@/pages/session/session-layout"
 import { SidePanelSubagents } from "@/pages/session/side-panel-subagents"
+import { isSubagentInterrupted } from "@/pages/session/subagent-state"
 import { SidePanelBrowser } from "@/pages/session/side-panel-browser"
 import { SidePanelWorktree } from "@/pages/session/side-panel-worktree"
 import { SidePanelDebug } from "@/pages/session/side-panel-debug"
@@ -135,11 +136,7 @@ export function SessionSidePanel(props: {
     () => subagentChildren().filter((s) => sync.data.session_working(s.id)).length,
   )
   const interruptedSubagentCount = createMemo(
-    () =>
-      subagentChildren().filter((s) => {
-        const sub = (s.metadata?.["deepagent"] as { subagent?: { interrupted?: boolean } } | undefined)?.subagent
-        return sub?.interrupted === true
-      }).length,
+    () => subagentChildren().filter(isSubagentInterrupted).length,
   )
   const subagentAttentionCount = createMemo(
     () => runningSubagentCount() + interruptedSubagentCount(),
diff --git a/packages/app/src/pages/session/side-panel-subagents.tsx b/packages/app/src/pages/session/side-panel-subagents.tsx
index 801e13ad..91a616fd 100644
--- a/packages/app/src/pages/session/side-panel-subagents.tsx
+++ b/packages/app/src/pages/session/side-panel-subagents.tsx
@@ -6,6 +6,7 @@ import { useNavigate, useParams } from "@solidjs/router"
 import { useSDK } from "@/context/sdk"
 import { fetchCapabilities } from "@/components/deepagent/panel-goal.api"
 import { OversightDashboard } from "@/components/deepagent/oversight-dashboard"
+import { isSubagentInterrupted } from "./subagent-state"
 
 // Phase 2 (§3): SidePanelSubagents is now the single "子Agent监督" entry for the right rail.
 // It holds a `selectedSessionID` to track which subagent is being inspected; that selection
@@ -23,6 +24,7 @@ import { OversightDashboard } from "@/components/deepagent/oversight-dashboard"
 // (scope+route SessionStateKey): that never equals a child's parentID, so the list was always
 // empty. Resolving it internally here (like SidePanelIM / SidePanelDebug do) keeps the contract
 // simple and immune to that mismatch.
+
 export const SidePanelSubagents: Component<{ onClose: () => void }> = (props) => {
   const sync = useSync()
   const language = useLanguage()
@@ -56,10 +58,7 @@ export const SidePanelSubagents: Component<{ onClose: () => void }> = (props) =>
     const sub = (child.metadata?.["deepagent"] as { subagent?: { finished?: boolean } } | undefined)?.subagent
     return sub?.finished === true
   }
-  const isInterrupted = (child: { metadata?: Record<string, unknown> }): boolean => {
-    const sub = (child.metadata?.["deepagent"] as { subagent?: { interrupted?: boolean } } | undefined)?.subagent
-    return sub?.interrupted === true
-  }
+  const isInterrupted = isSubagentInterrupted
   const statusOf = (
     child: { id: string; metadata?: Record<string, unknown> },
   ): "running" | "finished" | "interrupted" | "idle" => {
diff --git a/packages/app/src/pages/session/subagent-state.test.ts b/packages/app/src/pages/session/subagent-state.test.ts
new file mode 100644
index 00000000..e5ff23d2
--- /dev/null
+++ b/packages/app/src/pages/session/subagent-state.test.ts
@@ -0,0 +1,10 @@
+import { describe, expect, test } from "bun:test"
+import { isSubagentInterrupted } from "./subagent-state"
+
+describe("isSubagentInterrupted", () => {
+  test("recognizes durable state and legacy boolean interruption markers", () => {
+    expect(isSubagentInterrupted({ deepagent: { subagent: { state: "interrupted" } } })).toBe(true)
+    expect(isSubagentInterrupted({ deepagent: { subagent: { interrupted: true } } })).toBe(true)
+    expect(isSubagentInterrupted({ deepagent: { subagent: { state: "finished" } } })).toBe(false)
+  })
+})
diff --git a/packages/app/src/pages/session/subagent-state.ts b/packages/app/src/pages/session/subagent-state.ts
new file mode 100644
index 00000000..188ceafd
--- /dev/null
+++ b/packages/app/src/pages/session/subagent-state.ts
@@ -0,0 +1,10 @@
+type SubagentMetadata = {
+  state?: string
+  interrupted?: boolean
+}
+
+/** Supports durable state markers and legacy boolean interruption markers. */
+export const isSubagentInterrupted = (metadata?: Record<string, unknown>) => {
+  const subagent = (metadata?.["deepagent"] as { subagent?: SubagentMetadata } | undefined)?.subagent
+  return subagent?.state === "interrupted" || subagent?.interrupted === true
+}
diff --git a/packages/app/src/pages/session/terminal-view.tsx b/packages/app/src/pages/session/terminal-view.tsx
index 51f95c3e..3ff8df0e 100644
--- a/packages/app/src/pages/session/terminal-view.tsx
+++ b/packages/app/src/pages/session/terminal-view.tsx
@@ -309,6 +309,7 @@ function TerminalSessionView(props: { pty: LocalPTY; focused: boolean }) {
               autoFocus={props.focused}
               runtimeId={terminal.runtimeId()}
               onStatusChange={(next, error) => terminal.setStatus(props.pty.id, ptyId, next, error)}
+              optimisticReady={props.pty.restored}
             />
           )}
         </Show>
diff --git a/packages/core/src/database/migration.gen.ts b/packages/core/src/database/migration.gen.ts
index 715ec449..b8ff85ff 100644
--- a/packages/core/src/database/migration.gen.ts
+++ b/packages/core/src/database/migration.gen.ts
@@ -53,5 +53,6 @@ export const migrations = (
     import("./migration/20260712040000_deepagent_event_drop_distinct"),
     import("./migration/20260712050000_session_steer_queue"),
     import("./migration/20260719000000_deepagent_consumer_group"),
+    import("./migration/20260722000000_session_steer_correlation"),
   ])
 ).map((module) => module.default) satisfies DatabaseMigration.Migration[]
diff --git a/packages/core/src/database/migration/20260722000000_session_steer_correlation.ts b/packages/core/src/database/migration/20260722000000_session_steer_correlation.ts
new file mode 100644
index 00000000..472ff4d4
--- /dev/null
+++ b/packages/core/src/database/migration/20260722000000_session_steer_correlation.ts
@@ -0,0 +1,16 @@
+import { Effect } from "effect"
+import type { DatabaseMigration } from "../migration"
+
+export default {
+  id: "20260722000000_session_steer_correlation",
+  up(tx) {
+    return Effect.gen(function* () {
+      yield* tx.run(`ALTER TABLE session_steer ADD COLUMN correlation_id TEXT`)
+      yield* tx.run(`
+        CREATE UNIQUE INDEX IF NOT EXISTS session_steer_session_correlation_idx
+        ON session_steer (session_id, correlation_id)
+        WHERE correlation_id IS NOT NULL
+      `)
+    })
+  },
+} satisfies DatabaseMigration.Migration
diff --git a/packages/core/src/session/sql.ts b/packages/core/src/session/sql.ts
index 1b678fa9..c509d4a0 100644
--- a/packages/core/src/session/sql.ts
+++ b/packages/core/src/session/sql.ts
@@ -185,11 +185,15 @@ export const SessionSteerTable = sqliteTable(
   "session_steer",
   {
     seq: integer().primaryKey({ autoIncrement: true }),
+    // Canonical durable/V1 identity — always server-minted. Never reuse a client optimistic id.
     id: text().$type<SessionMessage.ID>().notNull().unique(),
     session_id: text()
       .$type<SessionSchema.ID>()
       .notNull()
       .references(() => SessionTable.id, { onDelete: "cascade" }),
+    // Optional client retry key isolated from the canonical durable message id. Identical retries
+    // return the stored row; different payload for the same key is a CorrelationConflict.
+    correlation_id: text(),
     prompt: text({ mode: "json" }).notNull().$type<Prompt>(),
     delivery: text().$type<SessionInput.Delivery>().notNull(),
     consumed_seq: integer(),
@@ -199,6 +203,7 @@ export const SessionSteerTable = sqliteTable(
   },
   (table) => [
     index("session_steer_session_pending_seq_idx").on(table.session_id, table.consumed_seq, table.seq),
+    uniqueIndex("session_steer_session_correlation_idx").on(table.session_id, table.correlation_id),
   ],
 )
 
diff --git a/packages/deepagent-code/src/session/prompt.ts b/packages/deepagent-code/src/session/prompt.ts
index 5403b577..9b7f201e 100644
--- a/packages/deepagent-code/src/session/prompt.ts
+++ b/packages/deepagent-code/src/session/prompt.ts
@@ -61,7 +61,7 @@ import { Truncate } from "@/tool/truncate"
 import { Image } from "@/image/image"
 import { decodeDataUrl } from "@/util/data-url"
 import { Process } from "@/util/process"
-import { Cause, Effect, Exit, Latch, Layer, Option, Scope, Context, Schema, Types } from "effect"
+import { Cause, Data, Effect, Exit, Latch, Layer, Option, Scope, Context, Schema, Types } from "effect"
 import * as EffectLogger from "@deepagent-code/core/effect/logger"
 import { InstanceState } from "@/effect/instance-state"
 import { TaskTool, type TaskPromptOps } from "@/tool/task"
@@ -144,14 +144,48 @@ function isOrphanedInterruptedTool(part: SessionV1.ToolPart) {
 // isTerminalGoalPhase (kept as a local const to avoid a circular import: goal-manager imports this file).
 const TERMINAL_GOAL_PHASES: ReadonlySet<string> = new Set(["done", "needs_human", "rolled_back", "stopped"])
 
-// §S1.2 — extract the plain text a steer should carry from a PromptInput's parts (text parts only; file/
-// agent/subtask attachments are not re-encoded into a steer's text — a steered turn is a user message).
-const promptInputText = (parts: PromptInput["parts"]): string =>
-  parts
+class InvalidInput extends Data.TaggedError("SessionPrompt.InvalidInput")<{ readonly message: string }> {}
+
+// §S1.2 — convert PromptInput parts to the durable Prompt model used by the steer buffer.
+// All part types that have a Prompt equivalent are preserved; subtask parts are explicitly rejected
+// so they never produce a silent empty steer. The steer caller should surface this as a client error.
+const promptInputToPrompt = (
+  parts: PromptInput["parts"],
+): Effect.Effect<Prompt, InvalidInput> => {
+  if (parts.some((p) => p.type === "subtask"))
+    return Effect.fail(
+      new InvalidInput({ message: "Subtask prompt parts cannot be steered while a session is busy" }),
+    )
+  const text = parts
     .filter((p): p is Extract<PromptInput["parts"][number], { type: "text" }> => p.type === "text")
     .map((p) => p.text)
     .join("\n")
     .trim()
+  const files = parts
+    .filter((p): p is Extract<PromptInput["parts"][number], { type: "file" }> => p.type === "file")
+    .map(
+      (p) =>
+        new FileAttachment({
+          uri: p.url,
+          mime: p.mime,
+          ...(p.filename !== undefined ? { name: p.filename } : {}),
+        }),
+    )
+  const agents = parts
+    .filter((p): p is Extract<PromptInput["parts"][number], { type: "agent" }> => p.type === "agent")
+    .map((p) => new AgentAttachment({ name: p.name }))
+  if (text.length === 0 && files.length === 0 && agents.length === 0)
+    return Effect.fail(
+      new InvalidInput({ message: "Steer prompt must contain at least one supported part" }),
+    )
+  return Effect.succeed(
+    Prompt.fromUserMessage({
+      text,
+      ...(files.length === 0 ? {} : { files }),
+      ...(agents.length === 0 ? {} : { agents }),
+    }),
+  )
+}
 
 export interface Interface {
   readonly cancel: (sessionID: SessionID) => Effect.Effect<void>
@@ -159,7 +193,12 @@ export interface Interface {
   // V4.1 §S1.1: buffer a mid-turn user message into the durable steer queue for absorption at the next
   // model-request boundary of the live turn loop. This is the admit() API; S1.2 wires the busy-session
   // ingress that decides WHEN to route a message here vs. the normal prompt() path. Idempotent on `id`.
-  readonly steer: (input: SteerInput) => Effect.Effect<SessionSteer.Admitted>
+  readonly steer: (input: {
+    sessionID: SessionID
+    prompt: Prompt
+    delivery?: SessionSteer.Delivery
+    messageID?: SessionMessage.ID
+  }) => Effect.Effect<SessionSteer.Admitted>
   // V4.1 §S1.2: the busy-session ingress decision. If the session is IDLE (no live turn) → run a normal
   // turn (prompt). If it is BUSY (mid-turn) and steering is enabled → buffer the message as a steer so
   // the running turn absorbs it at its next boundary (delivery="goal_steer" when a non-terminal goal is
@@ -1913,10 +1952,8 @@ export const layer = Layer.effect(
     // turn. The steer id is an ascending SessionMessage.ID minted at admit time, so tail-sorting (Check 3)
     // is preserved. This replaces the earlier stamp-then-persist ordering, whose crash window between the
     // consume stamp and the message write could lose a steer permanently.
-    const steerPartID = (messageID: MessageID) =>
-      // Deterministic, valid PartID (prt_<message-suffix>) so a replayed persist targets the SAME part
-      // row and the projector's onConflictDoUpdate makes it a no-op instead of appending a duplicate.
-      PartID.make("prt_" + messageID.slice("msg_".length))
+    const steerPartID = (messageID: MessageID, suffix?: string) =>
+      PartID.make("prt_" + messageID.slice("msg_".length) + (suffix ?? ""))
     const drainSteers = Effect.fn("SessionPrompt.drainSteers")(function* (sessionID: SessionID) {
       if (!flags.v4Steering) return 0
       const pending = yield* steerBuffer.pending(sessionID)
@@ -1952,17 +1989,35 @@ export const layer = Layer.effect(
             ...(variant ? { variant } : {}),
           },
         }
-        // PERSIST-FIRST: materialize the history message + its text part (both keyed by the steer id, so
-        // a replay after a mid-drain crash is an idempotent upsert, not a duplicate) BEFORE stamping the
-        // steer consumed below.
+        // PERSIST-FIRST: materialize the history message and all durable parts before stamping consumed.
+        // Part IDs are derived from the steer id so post-crash replays are idempotent upserts.
         yield* sessions.updateMessage(info)
-        yield* sessions.updatePart({
-          id: steerPartID(info.id),
-          messageID: info.id,
-          sessionID,
-          type: "text",
-          text: admitted.prompt.text,
-        })
+        if (admitted.prompt.text.length > 0)
+          yield* sessions.updatePart({
+            id: steerPartID(info.id),
+            messageID: info.id,
+            sessionID,
+            type: "text",
+            text: admitted.prompt.text,
+          })
+        for (const [i, file] of (admitted.prompt.files ?? []).entries())
+          yield* sessions.updatePart({
+            id: steerPartID(info.id, `_f${i}`),
+            messageID: info.id,
+            sessionID,
+            type: "file",
+            url: file.uri,
+            mime: file.mime,
+            filename: file.name ?? file.uri,
+          })
+        for (const [i, agent] of (admitted.prompt.agents ?? []).entries())
+          yield* sessions.updatePart({
+            id: steerPartID(info.id, `_a${i}`),
+            messageID: info.id,
+            sessionID,
+            type: "agent",
+            name: agent.name,
+          })
         persisted.push(admitted.id)
         yield* elog.info("steer absorbed at boundary", { sessionID, messageID: info.id, seq: admitted.seq })
       }
@@ -2599,39 +2654,38 @@ export const layer = Layer.effect(
       },
     )
 
-    // V4.1 §S1.1: admit a mid-turn user message into the durable steer buffer. Pure buffering — it does
-    // NOT interrupt the in-flight run; the runLoop absorbs it at its next model-request boundary (see
-    // drainSteers below). With the kill-switch OFF this is a no-op guard: the caller (S1.2 ingress)
-    // must not route here when steering is disabled, but we defensively refuse to buffer so an
-    // orphaned steer can never accumulate undrained. Idempotent on `id`.
-    const steer: (input: SteerInput) => Effect.Effect<SessionSteer.Admitted> = Effect.fn("SessionPrompt.steer")(
-      function* (input: SteerInput) {
-        if (!flags.v4Steering)
-          return yield* Effect.die(new NamedError.Unknown({ message: "Steering is disabled (v4Steering=false)" }))
-        const prompt = Prompt.fromUserMessage({
-          text: input.text,
-          ...(input.files === undefined ? {} : { files: input.files }),
-          ...(input.agents === undefined ? {} : { agents: input.agents }),
-          ...(input.references === undefined ? {} : { references: input.references }),
-        })
-        // §S1.3 delivery channel: "goal_steer" is drained by the goal driver between ticks; "steer"
-        // (default) by the session's own runLoop. The two never contend on the same buffer rows.
-        const delivery = input.delivery ?? "steer"
-        const admitted = yield* steerBuffer.admit({
-          id: input.messageID ?? SessionMessage.ID.create(),
-          sessionID: input.sessionID,
-          prompt,
-          delivery,
-        })
-        yield* elog.info("steer admitted", {
-          sessionID: input.sessionID,
-          messageID: admitted.id,
-          seq: admitted.seq,
-          delivery,
-        })
-        return admitted
-      },
-    )
+    // V4.1 §S1.1: admit a mid-turn user message into the durable steer buffer.
+    // The canonical durable ID is always server-minted by admit(); the caller's messageID is used
+    // only as an optional correlationID for idempotent retries.
+    const steer: (input: {
+      sessionID: SessionID
+      prompt: Prompt
+      delivery?: SessionSteer.Delivery
+      messageID?: SessionMessage.ID
+    }) => Effect.Effect<SessionSteer.Admitted> = Effect.fn(
+      "SessionPrompt.steer",
+    )(function* (input) {
+      if (!flags.v4Steering)
+        return yield* Effect.die(new NamedError.Unknown({ message: "Steering is disabled (v4Steering=false)" }))
+      const delivery = input.delivery ?? "steer"
+      const admitted = yield* steerBuffer.admit({
+        sessionID: input.sessionID,
+        prompt: input.prompt,
+        delivery,
+        correlationID: input.messageID,
+      }).pipe(
+        Effect.catchTag("SessionSteer.CorrelationConflict", () =>
+          Effect.die(new NamedError.Unknown({ message: "Steer correlation conflict: duplicate follow-up" })),
+        ),
+      )
+      yield* elog.info("steer admitted", {
+        sessionID: input.sessionID,
+        messageID: admitted.id,
+        seq: admitted.seq,
+        delivery,
+      })
+      return admitted
+    })
 
     // V4.1 §S1.2 — the ingress decision. Both the HTTP prompt route and the IM agent executor call THIS
     // instead of prompt() directly, so the steer-vs-turn choice lives in exactly one place.
@@ -2660,23 +2714,22 @@ export const layer = Layer.effect(
       const goal = AgentGateway.DeepAgentSessionState.getActiveGoal(input.sessionID)
       const goalActive = goal != null && !TERMINAL_GOAL_PHASES.has(goal.phase)
       if (goalActive) {
-        const text = promptInputText(input.parts)
+        const steerPrompt = yield* promptInputToPrompt(input.parts).pipe(
+          Effect.catchTag("SessionPrompt.InvalidInput", (e) =>
+            Effect.die(e),
+          ),
+        )
         const admitted = yield* steer({
           sessionID: input.sessionID,
-          text,
+          prompt: steerPrompt,
           delivery: "goal_steer",
-          // §S1.2 ID bridge: forward the client-supplied messageID so the steer row carries the same
-          // id as the frontend's optimistic message — prevents a duplicate entry when drainSteers
-          // materialises the steer into V1 history. PromptInput.messageID is a different Schema brand
-          // (MessageID vs SessionMessage.ID) but both are ascending-string ids at runtime; the cast is
-          // safe because sendFollowupDraft always mints via Identifier.ascending().
           messageID: input.messageID as unknown as SessionMessage.ID | undefined,
         })
         // V4.1 governance audit — this is the REAL user goal-steer path (the ingress every busy-goal
         // steer flows through). Record the human intervention into the goal's Document Graph alongside
         // the per-tick worklog trail. Length only (not free-text) to keep the body bounded + PII-light;
         // best-effort (never blocks the steer). goal!.goalId is safe here: goalActive ⇒ goal != null.
-        writeGovernanceAudit(input.sessionID, goal!.goalId, "steer", { textChars: text.trim().length })
+        writeGovernanceAudit(input.sessionID, goal!.goalId, "steer", { textChars: steerPrompt.text.trim().length })
         return { kind: "steer" as const, delivery: "goal_steer" as const, admitted }
       }
       // (3) No active goal → a parent chat turn in flight becomes a chat steer.
@@ -2686,15 +2739,14 @@ export const layer = Layer.effect(
         const message = yield* prompt(input)
         return { kind: "turn" as const, message }
       }
-      // §S1.2 ID bridge: forward the client-supplied messageID so the steer row carries the same id as
-      // the frontend's optimistic message — prevents a duplicate entry when drainSteers materialises
-      // the steer into V1 history. PromptInput.messageID is a different Schema brand (MessageID vs
-      // SessionMessage.ID) but both are ascending-string ids at runtime; the cast is safe because
-      // sendFollowupDraft always mints via Identifier.ascending(). steer() will still generate a fresh
-      // ascending id when messageID is omitted (e.g. non-async callers that don't supply one).
+      const steerPrompt = yield* promptInputToPrompt(input.parts).pipe(
+        Effect.catchTag("SessionPrompt.InvalidInput", (e) =>
+          Effect.die(e),
+        ),
+      )
       const admitted = yield* steer({
         sessionID: input.sessionID,
-        text: promptInputText(input.parts),
+        prompt: steerPrompt,
         delivery: "steer",
         messageID: input.messageID as unknown as SessionMessage.ID | undefined,
       })
diff --git a/packages/deepagent-code/src/session/steer.ts b/packages/deepagent-code/src/session/steer.ts
index 68c5b4cf..6a3a653a 100644
--- a/packages/deepagent-code/src/session/steer.ts
+++ b/packages/deepagent-code/src/session/steer.ts
@@ -1,5 +1,5 @@
 import { and, asc, eq, inArray, isNull } from "drizzle-orm"
-import { Context, DateTime, Effect, Layer, Schema } from "effect"
+import { Context, Data, DateTime, Effect, Layer, Schema } from "effect"
 import { Database } from "@deepagent-code/core/database/database"
 import { SessionInput } from "@deepagent-code/core/session/input"
 import { SessionMessage } from "@deepagent-code/core/session/message"
@@ -37,6 +37,14 @@ import { SessionID } from "./schema"
 
 export type Delivery = SessionInput.Delivery
 
+// Raised when the same correlationID is reused with a different payload, which
+// would silently overwrite or ignore the earlier steer. Callers should surface
+// this as a 409-style client error.
+export class CorrelationConflict extends Data.TaggedError("SessionSteer.CorrelationConflict")<{
+  readonly sessionID: SessionID
+  readonly correlationID: string
+}> {}
+
 export class Admitted extends Schema.Class<Admitted>("SessionSteer.Admitted")({
   seq: Schema.Int,
   id: SessionMessage.ID,
@@ -60,14 +68,15 @@ const fromRow = (row: typeof SessionSteerTable.$inferSelect): Admitted =>
   })
 
 export interface Interface {
-  // Buffer a user message for later absorption. Idempotent on `id` (a duplicate admit is a no-op and
-  // returns the already-stored record) so an at-least-once ingress (S1.2) never double-buffers.
+  // Buffer a user message for later absorption. `id` is always server-minted.
+  // `correlationID` is an optional client retry key: identical payload retries return the stored row;
+  // different payload for the same key returns a CorrelationConflict (never silently drops).
   readonly admit: (input: {
-    readonly id: SessionMessage.ID
     readonly sessionID: SessionID
     readonly prompt: Prompt
     readonly delivery?: Delivery
-  }) => Effect.Effect<Admitted>
+    readonly correlationID?: string
+  }) => Effect.Effect<Admitted, CorrelationConflict>
   // NON-consuming read of pending steers for the session, in send-order (ascending `seq`). Persist-first
   // step 1: the runLoop reads these, materializes each as a V1 history message keyed by the steer id
   // (idempotent), THEN calls markConsumed. Reading does NOT mark anything — a crash before markConsumed
@@ -98,11 +107,13 @@ export const layer = Layer.effect(
   Effect.gen(function* () {
     const { db } = yield* Database.Service
 
-    const find = (id: SessionMessage.ID) =>
+    const findByCorrelation = (sessionID: SessionID, correlationID: string) =>
       db
         .select()
         .from(SessionSteerTable)
-        .where(eq(SessionSteerTable.id, id))
+        .where(
+          and(eq(SessionSteerTable.session_id, sessionID), eq(SessionSteerTable.correlation_id, correlationID)),
+        )
         .get()
         .pipe(
           Effect.orDie,
@@ -112,25 +123,33 @@ export const layer = Layer.effect(
     const admit: Interface["admit"] = Effect.fn("SessionSteer.admit")(function* (input) {
       const delivery = input.delivery ?? "steer"
       const timeCreated = DateTime.toEpochMillis(yield* DateTime.now)
+      // Always server-minted: the canonical durable/V1 message ID is never client-supplied.
+      const id = SessionMessage.ID.create()
       const inserted = yield* db
         .insert(SessionSteerTable)
         .values({
-          id: input.id,
+          id,
           session_id: input.sessionID,
+          correlation_id: input.correlationID,
           prompt: encodePrompt(input.prompt),
           delivery,
           time_created: timeCreated,
         })
-        .onConflictDoNothing({ target: SessionSteerTable.id })
+        .onConflictDoNothing()
         .returning()
         .get()
         .pipe(Effect.orDie)
       if (inserted) return fromRow(inserted)
-      // Lost the insert race (id already admitted) — return the stored record. Consume-once means the
-      // caller must never re-buffer, so surfacing the existing row is the correct idempotent answer.
-      const existing = yield* find(input.id)
-      if (existing) return existing
-      return yield* Effect.die("SessionSteer.admit: conflicting row vanished")
+      // Correlation conflict path: another row with the same (session, correlationID) already exists.
+      if (input.correlationID === undefined)
+        return yield* Effect.die("SessionSteer.admit: server-generated id conflicted (impossible)")
+      const existing = yield* findByCorrelation(input.sessionID, input.correlationID)
+      if (!existing) return yield* Effect.die("SessionSteer.admit: conflicting correlation row vanished")
+      // Identical payload = idempotent retry; different payload = explicit conflict.
+      if (existing.delivery === delivery && Prompt.equivalence(existing.prompt, input.prompt)) return existing
+      return yield* Effect.fail(
+        new CorrelationConflict({ sessionID: input.sessionID, correlationID: input.correlationID }),
+      )
     })
 
     const pending: Interface["pending"] = Effect.fn("SessionSteer.pending")(function* (sessionID, delivery = "steer") {
diff --git a/packages/deepagent-code/src/session/v4-event-runtime.ts b/packages/deepagent-code/src/session/v4-event-runtime.ts
index 6f4281ac..256c67f0 100644
--- a/packages/deepagent-code/src/session/v4-event-runtime.ts
+++ b/packages/deepagent-code/src/session/v4-event-runtime.ts
@@ -461,16 +461,50 @@ const anyV4DaemonEnabled = (flags: RuntimeFlags.Info): boolean =>
 // Register the durable delivery policy before any V4 publisher can emit. `Layer.mergeAll` starts
 // components concurrently, so relying on each consumer's live subscribe stream loses first-start events.
 // Individual consumers repeat this idempotently for standalone use; this layer establishes the runtime
-// producer-after-registration boundary. Disabled groups are deliberately absent and accrue no backlog.
-const consumerRegistrationLayer = Layer.effectDiscard(
+// producer-after-registration boundary. The policy lists ONLY groups owned by this runtime, so reconciling
+// disabled flags and releasing this scope cannot remove a group owned by another feature or instance.
+type RuntimeConsumerGroup = {
+  readonly id: string
+  readonly typeFilter?: string
+  readonly enabled: (flags: RuntimeFlags.Info) => boolean
+}
+
+const runtimeConsumerGroups: ReadonlyArray<RuntimeConsumerGroup> = [
+  { id: DISPATCH_GROUP, enabled: anyV4DaemonEnabled },
+  {
+    id: TICK_GROUP,
+    typeFilter: LMNEvents.GOAL_TICK_REQUESTED,
+    enabled: (flags) => flags.v4MultiAgentRuntime,
+  },
+  { id: CONVENE_GROUP, enabled: (flags) => flags.v4PanelAutoConvene },
+  { id: ARCHIVE_GROUP, enabled: (flags) => flags.v4EventDrivenArchive || flags.v4MultiAgentRuntime },
+  { id: NOTIFY_GROUP, enabled: (flags) => flags.v4AgentPushEnabled },
+]
+
+// Exported for direct lifecycle testing. On startup this reconciles historical V4 groups left by an older
+// runtime: enabled groups are registered and disabled groups are removed. Scope release removes exactly
+// the enabled groups this runtime owned, stopping future publishes from accruing offline deliveries.
+export const consumerRegistrationLayer = Layer.effectDiscard(
   Effect.gen(function* () {
     const flags = yield* RuntimeFlags.Service
     const bus = yield* DeepAgentEventBus.Service
-    if (anyV4DaemonEnabled(flags)) yield* bus.registerConsumerGroup(DISPATCH_GROUP)
-    if (flags.v4MultiAgentRuntime) yield* bus.registerConsumerGroup(TICK_GROUP, LMNEvents.GOAL_TICK_REQUESTED)
-    if (flags.v4PanelAutoConvene) yield* bus.registerConsumerGroup(CONVENE_GROUP)
-    if (flags.v4EventDrivenArchive || flags.v4MultiAgentRuntime) yield* bus.registerConsumerGroup(ARCHIVE_GROUP)
-    if (flags.v4AgentPushEnabled) yield* bus.registerConsumerGroup(NOTIFY_GROUP)
+    const enabled = runtimeConsumerGroups.filter((group) => group.enabled(flags))
+    const disabled = runtimeConsumerGroups.filter((group) => !group.enabled(flags))
+
+    yield* Effect.forEach(enabled, (group) => bus.registerConsumerGroup(group.id, group.typeFilter), {
+      concurrency: "unbounded",
+      discard: true,
+    })
+    yield* Effect.forEach(disabled, (group) => bus.unregisterConsumerGroup(group.id), {
+      concurrency: "unbounded",
+      discard: true,
+    })
+    yield* Effect.addFinalizer(() =>
+      Effect.forEach(enabled, (group) => bus.unregisterConsumerGroup(group.id), {
+        concurrency: "unbounded",
+        discard: true,
+      }),
+    )
   }),
 )
 
diff --git a/packages/deepagent-code/src/tool/task_read.ts b/packages/deepagent-code/src/tool/task_read.ts
index 58f2c4f3..02d3c646 100644
--- a/packages/deepagent-code/src/tool/task_read.ts
+++ b/packages/deepagent-code/src/tool/task_read.ts
@@ -1,4 +1,5 @@
 import * as Tool from "./tool"
+import { MessageV2 } from "@/session/message-v2"
 import { Session } from "@/session/session"
 import { SessionV1 } from "@deepagent-code/core/v1/session"
 import { Effect, Schema } from "effect"
@@ -92,21 +93,18 @@ export const TaskReadTool = Tool.define(
         )
       }
 
-      // Read messages — Session.messages returns them oldest-first, we reverse for newest-first cursor.
-      const allMessages = yield* sessions
-        .messages({ sessionID: childSessionID, limit: MAX_LIMIT + 1 })
-        .pipe(Effect.catchCause(() => Effect.succeed([] as SessionV1.WithParts[])))
-
-      // Apply `before` cursor (message ID boundary for pagination).
-      const beforeID = params.before
-      const filteredMessages = beforeID
-        ? allMessages.filter((m) => m.info.id < beforeID)
-        : allMessages
-
-      // Take newest `limit` messages.
-      const page = filteredMessages.slice(-limit)
-      const hasMore = filteredMessages.length > limit
-      const nextCursor = page[0]?.info.id
+      // MessageV2.page applies the opaque cursor in storage and returns chronological items.
+      const result = yield* MessageV2.page({
+        sessionID: childSessionID,
+        limit,
+        before: params.before,
+      }).pipe(Effect.catchCause(() => Effect.succeed({ items: [] as SessionV1.WithParts[], more: false, cursor: undefined as string | undefined })))
+      const page = result.items
+      const nextCursor: string | undefined = result.cursor
+      // A cursor is the only valid continuation token. Never advertise another page when a
+      // storage implementation reports `more` without one: callers would resend `undefined`
+      // and restart from the newest messages.
+      const hasMore = result.more && nextCursor !== undefined
 
       // Read durable state from metadata.
       const deepagent = child.metadata?.["deepagent"] as Record<string, unknown> | undefined
@@ -167,7 +165,13 @@ export const TaskReadTool = Tool.define(
 
       return {
         title: `Task transcript: ${child.title ?? childSessionID}`,
-        metadata: { sessionID: childSessionID, state: durableState, messageCount: page.length, hasMore },
+        metadata: {
+          sessionID: childSessionID,
+          state: durableState,
+          messageCount: page.length,
+          hasMore,
+          ...(nextCursor !== undefined ? { before: nextCursor } : {}),
+        },
         output: transcript + paginationHint,
       }
     })
@@ -176,7 +180,7 @@ export const TaskReadTool = Tool.define(
       description: DESCRIPTION,
       parameters: Parameters,
       execute: (params: Schema.Schema.Type<typeof Parameters>, ctx: Tool.Context) =>
-        run(params, ctx).pipe(Effect.catchCause((cause) => Effect.die(cause))),
+        run(params, ctx).pipe(Effect.catchCause((cause) => Effect.die(cause))) as unknown as Effect.Effect<Tool.ExecuteResult>,
     }
   }),
 )
diff --git a/packages/deepagent-code/test/session/steer.test.ts b/packages/deepagent-code/test/session/steer.test.ts
index 5c32d47f..dbda5744 100644
--- a/packages/deepagent-code/test/session/steer.test.ts
+++ b/packages/deepagent-code/test/session/steer.test.ts
@@ -321,9 +321,9 @@ off.instance("admit buffers steers, pending returns them in send-order, markCons
     const sessions = yield* Session.Service
     const chat = yield* sessions.create({ title: "Steer unit" })
 
-    yield* steer.admit({ id: SessionMessage.ID.create(), sessionID: chat.id, prompt: mkPrompt("first") })
-    yield* steer.admit({ id: SessionMessage.ID.create(), sessionID: chat.id, prompt: mkPrompt("second") })
-    yield* steer.admit({ id: SessionMessage.ID.create(), sessionID: chat.id, prompt: mkPrompt("third") })
+    yield* steer.admit({ sessionID: chat.id, prompt: mkPrompt("first") })
+    yield* steer.admit({ sessionID: chat.id, prompt: mkPrompt("second") })
+    yield* steer.admit({ sessionID: chat.id, prompt: mkPrompt("third") })
 
     expect(yield* steer.hasPending(chat.id)).toBe(true)
 
@@ -358,9 +358,8 @@ off.instance(
 
       // On the SAME session id: one parent-chat steer (delivery="steer") and one goal-directed steer
       // (delivery="goal_steer"). This models a goal running in a session whose parent runLoop is also live.
-      yield* steer.admit({ id: SessionMessage.ID.create(), sessionID: chat.id, prompt: mkPrompt("chat steer") })
+      yield* steer.admit({ sessionID: chat.id, prompt: mkPrompt("chat steer") })
       yield* steer.admit({
-        id: SessionMessage.ID.create(),
         sessionID: chat.id,
         prompt: mkPrompt("goal guidance"),
         delivery: "goal_steer",
@@ -396,10 +395,10 @@ off.instance("admit is idempotent on message id (no double-buffer)", () =>
     const steer = yield* SessionSteer.Service
     const sessions = yield* Session.Service
     const chat = yield* sessions.create({ title: "Steer idempotent" })
-    const id = SessionMessage.ID.create()
+    const correlationID = SessionMessage.ID.create()
 
-    const a = yield* steer.admit({ id, sessionID: chat.id, prompt: mkPrompt("once") })
-    const b = yield* steer.admit({ id, sessionID: chat.id, prompt: mkPrompt("once") })
+    const a = yield* steer.admit({ correlationID, sessionID: chat.id, prompt: mkPrompt("once") })
+    const b = yield* steer.admit({ correlationID, sessionID: chat.id, prompt: mkPrompt("once") })
     expect(a.seq).toBe(b.seq)
 
     const drained = yield* steer.pending(chat.id)
@@ -418,7 +417,6 @@ off.instance("consume-once survives a fresh drain cycle (durable, no double-appl
     const chat = yield* sessions.create({ title: "Steer durable" })
 
     const admitted = yield* steer.admit({
-      id: SessionMessage.ID.create(),
       sessionID: chat.id,
       prompt: mkPrompt("persisted"),
     })
@@ -479,7 +477,6 @@ off.instance(
       const chat = yield* sessions.create({ title: "Steer crash window" })
 
       const admitted = yield* steer.admit({
-        id: SessionMessage.ID.create(),
         sessionID: chat.id,
         prompt: mkPrompt("DONT-LOSE-ME"),
       })
@@ -548,7 +545,6 @@ on.instance(
 
       // Admit the steer while the first model request is in flight.
       const admitted = yield* steer.admit({
-        id: SessionMessage.ID.create(),
         sessionID: chat.id,
         prompt: mkPrompt("STEERED-MESSAGE"),
       })
@@ -613,7 +609,7 @@ on.instance(
         .prompt({ sessionID: chat.id, agent: "build", model: ref, parts: [{ type: "text", text: "initial" }] })
         .pipe(Effect.forkChild)
       yield* llm.wait(1)
-      yield* steer.admit({ id: SessionMessage.ID.create(), sessionID: chat.id, prompt: mkPrompt("STEER") })
+      yield* steer.admit({ sessionID: chat.id, prompt: mkPrompt("STEER") })
       yield* Deferred.succeed(gate, void 0)
       yield* Fiber.await(fiber)
 
@@ -660,7 +656,7 @@ off.instance(
       })
 
       // Pre-buffer a steer directly (bypassing ingress) so we can prove the loop ignores it when OFF.
-      yield* steer.admit({ id: SessionMessage.ID.create(), sessionID: chat.id, prompt: mkPrompt("IGNORED-STEER") })
+      yield* steer.admit({ sessionID: chat.id, prompt: mkPrompt("IGNORED-STEER") })
 
       yield* llm.text("done")
       const result = yield* prompt.prompt({
@@ -832,7 +828,6 @@ on.instance(
 
       // A steer lands in the isBusy→admit race window (buffered while the session is idle).
       const admitted = yield* steer.admit({
-        id: SessionMessage.ID.create(),
         sessionID: drained.id,
         prompt: mkPrompt("STEP0-STEER"),
       })
@@ -864,7 +859,7 @@ on.instance(
       yield* llm.text("first-answer-2")
       yield* prompt.prompt({ sessionID: normal.id, agent: "build", model: ref, parts: [{ type: "text", text: "initial" }] })
       const before = yield* llm.calls
-      yield* steer.admit({ id: SessionMessage.ID.create(), sessionID: normal.id, prompt: mkPrompt("NOT-DRAINED") })
+      yield* steer.admit({ sessionID: normal.id, prompt: mkPrompt("NOT-DRAINED") })
 
       // Default loop() → drainFirst=false. Step 0 does NOT drain; the loop breaks at the finish check.
       yield* prompt.loop({ sessionID: normal.id })
diff --git a/packages/deepagent-code/test/session/v4-event-runtime.test.ts b/packages/deepagent-code/test/session/v4-event-runtime.test.ts
index 3e4fe3dc..31cf452e 100644
--- a/packages/deepagent-code/test/session/v4-event-runtime.test.ts
+++ b/packages/deepagent-code/test/session/v4-event-runtime.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect } from "bun:test"
-import { Deferred, Effect, Exit, Fiber, Layer } from "effect"
+import { Context, Deferred, Effect, Exit, Fiber, Layer } from "effect"
+import * as Scope from "effect/Scope"
 import { V4EventRuntime } from "../../src/session/v4-event-runtime"
 import { DeepAgentEventBus } from "@deepagent-code/core/deepagent/deepagent-event-bus"
 import { DeepAgentEvent } from "@deepagent-code/core/deepagent/deepagent-event"
@@ -59,8 +60,85 @@ describe("V4EventRuntime.layer", () => {
   )
 })
 
-// P1.6 — the production schedule bootstrap. Proves the tick loop now has real rows: registration is
-// flag-gated, idempotent across restarts, and the "3× CI failure → repair" condition fires when seeded.
+// Durable group lifecycle: registration must be reconciled when flags change, and scope release must
+// unregister only the groups this runtime owns so later publishes cannot leave an offline backlog.
+describe("V4EventRuntime durable consumer-group lifecycle", () => {
+  const staleRuntimeGroups = ["event-dispatcher", "goal-tick-consumer", "panel-convener", "wiki-archiver", "supervisor-notifier"]
+  const externalGroup = "other-feature-consumer"
+
+  const registration = (flags: Partial<RuntimeFlags.Info>) =>
+    V4EventRuntime.consumerRegistrationLayer.pipe(Layer.provide(RuntimeFlags.layer(flags)))
+
+  const fullRuntimeFlagsOff: Partial<RuntimeFlags.Info> = {
+    v4MultiAgentRuntime: false,
+    v4EventDrivenIm: false,
+    v4PanelAutoConvene: false,
+    v4EventDrivenArchive: false,
+    v4AgentPushEnabled: false,
+  }
+
+  const publish = (key: string): DeepAgentEvent.PublishInput => ({
+    type: "monitor.alert",
+    source: "monitor",
+    workspaceID: "wrk_1",
+    idempotencyKey: key,
+    priority: "normal",
+    payload: {},
+  })
+
+  baseIt.effect("enabled runtime registers its groups; a subsequent disabled startup removes only those historical groups", () =>
+    Effect.gen(function* () {
+      const busScope = yield* Scope.make()
+      const busContext = yield* Layer.build(
+        DeepAgentEventBus.layer.pipe(Layer.provideMerge(Database.layerFromPath(":memory:"))),
+      ).pipe(Scope.provide(busScope))
+      const bus = Context.get(busContext, DeepAgentEventBus.Service)
+
+      const enabledScope = yield* Scope.make()
+      yield* Layer.build(registration({ v4MultiAgentRuntime: true })).pipe(
+        Scope.provide(enabledScope),
+        Effect.provide(busContext),
+      )
+      yield* bus.registerConsumerGroup(externalGroup)
+      yield* Scope.close(enabledScope, Exit.void)
+
+      const disabledScope = yield* Scope.make()
+      yield* Layer.build(registration(fullRuntimeFlagsOff)).pipe(
+        Scope.provide(disabledScope),
+        Effect.provide(busContext),
+      )
+      const event = yield* bus.publish(publish("flags-off"))
+      const due = yield* bus.dueRetries(Number.MAX_SAFE_INTEGER)
+
+      expect(due.some((delivery) => delivery.eventID === event.id && staleRuntimeGroups.includes(delivery.subscriptionGroup))).toBe(false)
+      expect(due.some((delivery) => delivery.eventID === event.id && delivery.subscriptionGroup === externalGroup)).toBe(true)
+      yield* Scope.close(disabledScope, Exit.void)
+      yield* Scope.close(busScope, Exit.void)
+    }),
+  )
+
+  baseIt.effect("scope release unregisters enabled groups, so later publishes create no V4 delivery", () =>
+    Effect.gen(function* () {
+      const busScope = yield* Scope.make()
+      const busContext = yield* Layer.build(
+        DeepAgentEventBus.layer.pipe(Layer.provideMerge(Database.layerFromPath(":memory:"))),
+      ).pipe(Scope.provide(busScope))
+      const bus = Context.get(busContext, DeepAgentEventBus.Service)
+      const registrationScope = yield* Scope.make()
+      yield* Layer.build(registration({ v4MultiAgentRuntime: true })).pipe(
+        Scope.provide(registrationScope),
+        Effect.provide(busContext),
+      )
+      yield* Scope.close(registrationScope, Exit.void)
+
+      const event = yield* bus.publish(publish("after-release"))
+      const due = yield* bus.dueRetries(Number.MAX_SAFE_INTEGER)
+      expect(due.some((delivery) => delivery.eventID === event.id && staleRuntimeGroups.includes(delivery.subscriptionGroup))).toBe(false)
+      yield* Scope.close(busScope, Exit.void)
+    }),
+  )
+})
+
 describe("V4EventRuntime schedule bootstrap", () => {
   const database = Database.layerFromPath(":memory:")
   const it = testEffect(Scheduler.defaultLayer.pipe(Layer.provideMerge(database)))
diff --git a/packages/deepagent-code/test/tool/task-read.test.ts b/packages/deepagent-code/test/tool/task-read.test.ts
new file mode 100644
index 00000000..8e40c4cb
--- /dev/null
+++ b/packages/deepagent-code/test/tool/task-read.test.ts
@@ -0,0 +1,107 @@
+import { afterEach, describe, expect } from "bun:test"
+import { Effect, Layer } from "effect"
+import { Agent } from "../../src/agent/agent"
+import { BackgroundJob } from "@/background/job"
+import { EventV2Bridge } from "@/event-v2-bridge"
+import { Config } from "@/config/config"
+import { CrossSpawnSpawner } from "@deepagent-code/core/cross-spawn-spawner"
+import { Session } from "@/session/session"
+import { SessionRunState } from "@/session/run-state"
+import { SessionStatus } from "@/session/status"
+import { Database } from "@deepagent-code/core/database/database"
+import { MessageID, PartID, SessionID } from "../../src/session/schema"
+import { ModelV2 } from "@deepagent-code/core/model"
+import { ProviderV2 } from "@deepagent-code/core/provider"
+import { TaskReadTool } from "../../src/tool/task_read"
+import { Truncate } from "@/tool/truncate"
+import { ToolRegistry } from "@/tool/registry"
+import { RuntimeFlags } from "@/effect/runtime-flags"
+import { disposeAllInstances } from "../fixture/fixture"
+import { testEffect } from "../lib/effect"
+
+afterEach(async () => {
+  await disposeAllInstances()
+})
+
+const it = testEffect(
+  Layer.mergeAll(
+    Agent.defaultLayer,
+    BackgroundJob.defaultLayer,
+    EventV2Bridge.defaultLayer,
+    Config.defaultLayer,
+    CrossSpawnSpawner.defaultLayer,
+    Session.defaultLayer,
+    SessionRunState.defaultLayer,
+    SessionStatus.defaultLayer,
+    Truncate.defaultLayer,
+    ToolRegistry.defaultLayer,
+    Database.defaultLayer,
+    RuntimeFlags.layer(),
+  ),
+)
+
+const execCtx = (sessionID: SessionID) => ({
+  sessionID,
+  messageID: MessageID.ascending(),
+  agent: "build",
+  abort: new AbortController().signal,
+  extra: {},
+  messages: [],
+  metadata: () => Effect.void,
+  ask: () => Effect.void,
+})
+
+const addTextMessage = (sessionID: SessionID, text: string, created = Date.now()) =>
+  Effect.gen(function* () {
+    const sessions = yield* Session.Service
+    const message = yield* sessions.updateMessage({
+      id: MessageID.ascending(),
+      role: "user",
+      sessionID,
+      agent: "build",
+      model: { providerID: ProviderV2.ID.make("test"), modelID: ModelV2.ID.make("test") },
+      time: { created },
+    })
+    yield* sessions.updatePart({
+      id: PartID.ascending(),
+      sessionID,
+      messageID: message.id,
+      type: "text",
+      text,
+    })
+  })
+
+const readTexts = (output: string) => [...output.matchAll(/<message[^>]*>\s*([^<]+?)\s*<\/message>/g)].map((match) => match[1])
+
+describe("tool.task_read", () => {
+  it.instance("pages 203 child messages through storage cursors without duplicates", () =>
+    Effect.gen(function* () {
+      const sessions = yield* Session.Service
+      const parent = yield* sessions.create({ title: "Parent" })
+      const child = yield* sessions.create({ parentID: parent.id, agent: "general", title: "Long task" })
+      const expected = Array.from({ length: 203 }, (_, index) => `message-${String(index + 1).padStart(3, "0")}`)
+
+      for (const [index, text] of expected.entries()) yield* addTextMessage(child.id, text, 1_700_000_000_000 + index)
+
+      const tool = yield* TaskReadTool
+      const def = yield* tool.init()
+      const first = yield* def.execute({ task_id: child.id, limit: 100 }, execCtx(parent.id))
+      const second = yield* def.execute(
+        { task_id: child.id, limit: 100, before: first.metadata.before },
+        execCtx(parent.id),
+      )
+      const third = yield* def.execute(
+        { task_id: child.id, limit: 100, before: second.metadata.before },
+        execCtx(parent.id),
+      )
+
+      expect(first.metadata.hasMore).toBe(true)
+      expect(second.metadata.hasMore).toBe(true)
+      expect(third.metadata.hasMore).toBe(false)
+      expect(readTexts(first.output)).toEqual(expected.slice(103))
+      expect(readTexts(second.output)).toEqual(expected.slice(3, 103))
+      expect(readTexts(third.output)).toEqual(expected.slice(0, 3))
+      expect([...readTexts(third.output), ...readTexts(second.output), ...readTexts(first.output)]).toEqual(expected)
+    }),
+  )
+})