diff --git a/.changeset/agent-manager-modal-mode-shortcut.md b/.changeset/agent-manager-modal-mode-shortcut.md
deleted file mode 100644
index 4efdaa9bc43..00000000000
--- a/.changeset/agent-manager-modal-mode-shortcut.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"kilo-code": patch
----
-
-Fix Agent Manager mode shortcuts in the New Worktree dialog so the selected mode and its matching model stay in sync.
diff --git a/.changeset/bright-files-count.md b/.changeset/bright-files-count.md
deleted file mode 100644
index 84e4aa4fa2b..00000000000
--- a/.changeset/bright-files-count.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"kilo-code": patch
----
-
-Show aggregate added and removed line counts for multi-file patch tool calls.
diff --git a/.changeset/bright-project-dnd.md b/.changeset/bright-project-dnd.md
deleted file mode 100644
index 750341b6225..00000000000
--- a/.changeset/bright-project-dnd.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"kilo-code": patch
----
-
-Restore Agent Manager sections and worktree drag-and-drop when multiple projects are shown, with ordering and section moves scoped to the owning project.
diff --git a/.changeset/calm-location-watchers.md b/.changeset/calm-location-watchers.md
new file mode 100644
index 00000000000..cb9c384b6ee
--- /dev/null
+++ b/.changeset/calm-location-watchers.md
@@ -0,0 +1,6 @@
+---
+"@kilocode/cli": patch
+"kilo-code": patch
+---
+
+Prevent VS Code sessions and Agent Manager worktrees from starting unused file watchers and defer file indexing until search is used.
diff --git a/.changeset/compaction-threshold-boundary.md b/.changeset/compaction-threshold-boundary.md
deleted file mode 100644
index 2e610dbefb0..00000000000
--- a/.changeset/compaction-threshold-boundary.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"@kilocode/cli": patch
----
-
-Prevent configured compaction thresholds from interrupting active tool sequences.
diff --git a/.changeset/explain-tool-auto-approval-tui.md b/.changeset/explain-tool-auto-approval-tui.md
deleted file mode 100644
index df3e2f5cd03..00000000000
--- a/.changeset/explain-tool-auto-approval-tui.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"@kilocode/cli": minor
----
-
-Show why a tool call was auto-approved or denied in the TUI, and record the denial reason on the tool call metadata (visible in `kilo export`) alongside the existing auto-approval reason.
diff --git a/.changeset/fair-subagents-route.md b/.changeset/fair-subagents-route.md
deleted file mode 100644
index a1d2775fc90..00000000000
--- a/.changeset/fair-subagents-route.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"@kilocode/cli": patch
----
-
-Keep config-defined subagents routable when an installed primary agent uses the same name.
diff --git a/.changeset/fast-local-recall.md b/.changeset/fast-local-recall.md
deleted file mode 100644
index a2cc81e647c..00000000000
--- a/.changeset/fast-local-recall.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"@kilocode/cli": patch
----
-
-Speed up local session recall searches across large conversation histories.
diff --git a/.changeset/faster-macos-speech.md b/.changeset/faster-macos-speech.md
deleted file mode 100644
index 2d9bd9cc258..00000000000
--- a/.changeset/faster-macos-speech.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"kilo-code": patch
----
-
-Start voice input faster on macOS with native AVFoundation capture.
diff --git a/.changeset/fix-agent-manager-focus.md b/.changeset/fix-agent-manager-focus.md
deleted file mode 100644
index f8d5d6c65e3..00000000000
--- a/.changeset/fix-agent-manager-focus.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"kilo-code": patch
----
-
-Restore keyboard focus to the prompt or pending question when switching Agent Manager worktrees and sessions.
diff --git a/.changeset/fix-multi-project-navigation.md b/.changeset/fix-multi-project-navigation.md
new file mode 100644
index 00000000000..4eddfc5eb17
--- /dev/null
+++ b/.changeset/fix-multi-project-navigation.md
@@ -0,0 +1,5 @@
+---
+"kilo-code": patch
+---
+
+Fix multi-project Agent Manager keyboard navigation and Cmd/Ctrl shortcut selection when worktrees are grouped in sections.
diff --git a/.changeset/fix-multi-project-progress.md b/.changeset/fix-multi-project-progress.md
new file mode 100644
index 00000000000..53ccaf57301
--- /dev/null
+++ b/.changeset/fix-multi-project-progress.md
@@ -0,0 +1,5 @@
+---
+"kilo-code": patch
+---
+
+Fix Agent Manager progress indicators when multiple projects are expanded.
diff --git a/.changeset/fix-multi-project-session-scope.md b/.changeset/fix-multi-project-session-scope.md
new file mode 100644
index 00000000000..d56c4c93018
--- /dev/null
+++ b/.changeset/fix-multi-project-session-scope.md
@@ -0,0 +1,5 @@
+---
+"kilo-code": patch
+---
+
+Scope Agent Manager session events and Git status to the active project, including edits inside nested repositories.
diff --git a/.changeset/grep-signal-controls.md b/.changeset/grep-signal-controls.md
deleted file mode 100644
index 917e6ed2f59..00000000000
--- a/.changeset/grep-signal-controls.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"@kilocode/cli": patch
----
-
-Add bounded, context-aware signal-to-noise controls to grep searches.
diff --git a/.changeset/instant-worktree-hover.md b/.changeset/instant-worktree-hover.md
deleted file mode 100644
index e95e1af87ba..00000000000
--- a/.changeset/instant-worktree-hover.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"kilo-code": patch
----
-
-Show and hide Agent Manager worktree hover cards instantly.
diff --git a/.changeset/jetbrains-attachment-button-sync.md b/.changeset/jetbrains-attachment-button-sync.md
deleted file mode 100644
index dc86abba24e..00000000000
--- a/.changeset/jetbrains-attachment-button-sync.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"@kilocode/kilo-jetbrains": patch
----
-
-Keep the JetBrains prompt send/stop button in sync when attachments are added or removed while a session is busy.
diff --git a/.changeset/jetbrains-cli-checksums.md b/.changeset/jetbrains-cli-checksums.md
new file mode 100644
index 00000000000..186ae55675e
--- /dev/null
+++ b/.changeset/jetbrains-cli-checksums.md
@@ -0,0 +1,5 @@
+---
+"@kilocode/kilo-jetbrains": patch
+---
+
+Avoid GitHub API rate-limit failures when the JetBrains plugin downloads the pinned Kilo CLI.
diff --git a/.changeset/jetbrains-diff-view-fixes.md b/.changeset/jetbrains-diff-view-fixes.md
deleted file mode 100644
index 9fc6246c69b..00000000000
--- a/.changeset/jetbrains-diff-view-fixes.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"@kilocode/kilo-jetbrains": patch
----
-
-Fix JetBrains diff views to show compact workspace-relative file paths and keep added-file content visible in large branch diffs.
diff --git a/.changeset/jetbrains-file-drop-references.md b/.changeset/jetbrains-file-drop-references.md
new file mode 100644
index 00000000000..e801c8ba498
--- /dev/null
+++ b/.changeset/jetbrains-file-drop-references.md
@@ -0,0 +1,5 @@
+---
+"@kilocode/kilo-jetbrains": patch
+---
+
+Fix dropping files into the JetBrains prompt so code files are added as readable file references and drops anywhere in the session panel feed the prompt attachments.
diff --git a/.changeset/jetbrains-session-load-crop.md b/.changeset/jetbrains-session-load-crop.md
deleted file mode 100644
index 4e515cb3041..00000000000
--- a/.changeset/jetbrains-session-load-crop.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"@kilocode/kilo-jetbrains": patch
----
-
-Fix JetBrains chat transcripts rendering cropped when opening existing sessions.
diff --git a/.changeset/persist-project-accordion.md b/.changeset/persist-project-accordion.md
new file mode 100644
index 00000000000..6fda8a714a6
--- /dev/null
+++ b/.changeset/persist-project-accordion.md
@@ -0,0 +1,5 @@
+---
+"kilo-code": patch
+---
+
+Allow Agent Manager project headers to collapse or expand their project body, and persist that state across panel opens and VS Code restarts.
diff --git a/.changeset/project-local-navigation-hints.md b/.changeset/project-local-navigation-hints.md
new file mode 100644
index 00000000000..f6acca80ecd
--- /dev/null
+++ b/.changeset/project-local-navigation-hints.md
@@ -0,0 +1,5 @@
+---
+"kilo-code": patch
+---
+
+Show previous and next navigation hints using each project's own Agent Manager sidebar order.
diff --git a/.changeset/project-row-isolation.md b/.changeset/project-row-isolation.md
new file mode 100644
index 00000000000..fe1129c2cc6
--- /dev/null
+++ b/.changeset/project-row-isolation.md
@@ -0,0 +1,5 @@
+---
+"kilo-code": patch
+---
+
+Keep Agent Manager worktree rows isolated when projects contain identical raw worktree IDs.
diff --git a/.changeset/prompt-training-indicator-height.md b/.changeset/prompt-training-indicator-height.md
deleted file mode 100644
index e1842cbfef4..00000000000
--- a/.changeset/prompt-training-indicator-height.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"kilo-code": patch
----
-
-Keep the prompt controls at a consistent height when the model selector shows the prompt-training indicator.
diff --git a/.changeset/quick-model-search.md b/.changeset/quick-model-search.md
deleted file mode 100644
index 5b01ee44f97..00000000000
--- a/.changeset/quick-model-search.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"kilo-code": patch
----
-
-Update model search results instantly and keep the active match visible while typing.
diff --git a/.changeset/quiet-agent-sections.md b/.changeset/quiet-agent-sections.md
deleted file mode 100644
index b6d8d079c04..00000000000
--- a/.changeset/quiet-agent-sections.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"kilo-code": patch
----
-
-Allow Agent Manager sessions to move their worktree between sections or ungroup it through the `agent_manager` tool.
diff --git a/.changeset/quiet-metadata-generators.md b/.changeset/quiet-metadata-generators.md
deleted file mode 100644
index 67bb87bcbd9..00000000000
--- a/.changeset/quiet-metadata-generators.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"@kilocode/cli": patch
----
-
-Keep Kilo's persona out of generated conversation titles and Agent Manager branch names.
diff --git a/.changeset/quiet-speech-shortcut.md b/.changeset/quiet-speech-shortcut.md
deleted file mode 100644
index aa18416e3b6..00000000000
--- a/.changeset/quiet-speech-shortcut.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"kilo-code": patch
----
-
-Bind voice input to Cmd/Ctrl+K in Kilo prompt and review comment fields, with hold-to-talk and release-to-send support.
diff --git a/.changeset/quiet-terminals-focus.md b/.changeset/quiet-terminals-focus.md
deleted file mode 100644
index 22715b263ae..00000000000
--- a/.changeset/quiet-terminals-focus.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"kilo-code": patch
----
-
-Preserve prompt or Agent Manager terminal focus independently for each session when switching sessions.
diff --git a/.changeset/quiet-terminals-recover.md b/.changeset/quiet-terminals-recover.md
deleted file mode 100644
index 99c87f0de2f..00000000000
--- a/.changeset/quiet-terminals-recover.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"kilo-code": patch
----
-
-Start a fresh shell in the same Agent Manager terminal tab when the user types after the terminal ends.
diff --git a/.changeset/remove-project-selection-indicator.md b/.changeset/remove-project-selection-indicator.md
new file mode 100644
index 00000000000..50aee2c720f
--- /dev/null
+++ b/.changeset/remove-project-selection-indicator.md
@@ -0,0 +1,5 @@
+---
+"kilo-code": patch
+---
+
+Remove the redundant selected-project indicator from Agent Manager.
diff --git a/.changeset/session-resume-import.md b/.changeset/session-resume-import.md
new file mode 100644
index 00000000000..5243f666e01
--- /dev/null
+++ b/.changeset/session-resume-import.md
@@ -0,0 +1,5 @@
+---
+"@kilocode/cli": minor
+---
+
+Import conversation history from Claude Code and OpenAI Codex sessions with the /resume-claude and /resume-codex slash commands.
diff --git a/.changeset/single-agent-manager-empty-state.md b/.changeset/single-agent-manager-empty-state.md
new file mode 100644
index 00000000000..f3d9d0d35f6
--- /dev/null
+++ b/.changeset/single-agent-manager-empty-state.md
@@ -0,0 +1,5 @@
+---
+"kilo-code": patch
+---
+
+Show only one empty-state panel after removing the last Agent Manager worktree.
diff --git a/.changeset/skill-shell-inline-docs.md b/.changeset/skill-shell-inline-docs.md
deleted file mode 100644
index a0e1e864dfb..00000000000
--- a/.changeset/skill-shell-inline-docs.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"@kilocode/cli": patch
----
-
-Stop treating `` !`cmd` `` shown as an inline code example in skill documentation as a live command, so it no longer triggers a shell permission prompt.
diff --git a/.changeset/sync-inspector-width.md b/.changeset/sync-inspector-width.md
new file mode 100644
index 00000000000..02eeb4e7239
--- /dev/null
+++ b/.changeset/sync-inspector-width.md
@@ -0,0 +1,5 @@
+---
+"kilo-code": patch
+---
+
+Persist the Agent Manager inspector width and share it between the terminal and diff viewer.
diff --git a/.changeset/tui-paste-expand-placeholder.md b/.changeset/tui-paste-expand-placeholder.md
deleted file mode 100644
index 07b963ca0bb..00000000000
--- a/.changeset/tui-paste-expand-placeholder.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"@kilocode/cli": minor
----
-
-A second identical large paste expands its collapsed prompt placeholder.
\ No newline at end of file
diff --git a/.changeset/vscode-skills-settings-narrow-overflow.md b/.changeset/vscode-skills-settings-narrow-overflow.md
deleted file mode 100644
index bbdb87be496..00000000000
--- a/.changeset/vscode-skills-settings-narrow-overflow.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"kilo-code": patch
----
-
-Fix skill folder path and URL rows clipping and pushing the remove (×) button off-screen in narrow Skills settings panels. Long paths and URLs now truncate within their row, and hovering a truncated value shows the full path or URL in a tooltip.
diff --git a/.changeset/workflow-model-variants.md b/.changeset/workflow-model-variants.md
deleted file mode 100644
index 48b090358ce..00000000000
--- a/.changeset/workflow-model-variants.md
+++ /dev/null
@@ -1,6 +0,0 @@
----
-"@kilocode/cli": minor
-"kilo-code": minor
----
-
-Configure a model and reasoning variant for each workflow from Agent Behaviour settings.
diff --git a/.changeset/worktree-rename-focus.md b/.changeset/worktree-rename-focus.md
new file mode 100644
index 00000000000..fef1fe11e23
--- /dev/null
+++ b/.changeset/worktree-rename-focus.md
@@ -0,0 +1,5 @@
+---
+"kilo-code": patch
+---
+
+Keep multi-project worktree rename inputs focused while selection updates are still settling.
diff --git a/.github/docs-sync/edit-prompt.md b/.github/docs-sync/edit-prompt.md
index c9a2b86abed..0a3b7a98e1d 100644
--- a/.github/docs-sync/edit-prompt.md
+++ b/.github/docs-sync/edit-prompt.md
@@ -21,6 +21,7 @@ Hard rules:
 - Never remove or rename pages. Never document unreleased behavior. Never copy internal PR discussion into the docs; write user-facing documentation.
 - Do not run git commands and do not commit anything; automation handles git.
 - Keep the change small and precise. Do not rewrite sections that are already accurate.
+- Never create, modify, or delete packages/kilo-docs/LEARNINGS.md. Automation owns that file.
 
 When finished, write the summary JSON file named in the batch specifics below: a JSON array with exactly one entry per batch PR, consumed by automation (this file is never committed). Use `action` values like `updated <path>`, `created <path>`, or `skipped`. Example:
 
diff --git a/.github/docs-sync/edit.mjs b/.github/docs-sync/edit.mjs
index 167656eda35..15b89734edc 100644
--- a/.github/docs-sync/edit.mjs
+++ b/.github/docs-sync/edit.mjs
@@ -19,6 +19,7 @@ import fs from "node:fs"
 import path from "node:path"
 import { fileURLToPath } from "node:url"
 import { backoffMsForAttempt, deadline, remainingMs, runKilo, sleepSync } from "./lib.mjs"
+import { readLearningsBlock } from "./learn.mjs"
 
 const BATCH_SIZE = 5
 const ATTEMPTS = 3
@@ -26,7 +27,7 @@ const OUT_DIR = "docs-sync-out"
 export const SUMMARY_FILE = ".docs-sync-summary.json"
 
 const HERE = path.dirname(fileURLToPath(import.meta.url))
-const basePrompt = fs.readFileSync(path.join(HERE, "edit-prompt.md"), "utf8")
+const basePrompt = fs.readFileSync(path.join(HERE, "edit-prompt.md"), "utf8") + readLearningsBlock("edit")
 const model = process.env.EDIT_MODEL
 if (!model) throw new Error("EDIT_MODEL is required")
 
@@ -58,14 +59,7 @@ function editBatch(batch, index, budgetDeadline) {
   const triageFile = `${OUT_DIR}/edit-batch-triage-${index}.json`
   const summaryFile = `${OUT_DIR}/edit-summary-${index}.json`
   fs.writeFileSync(batchFile, JSON.stringify(batch, null, 2))
-  fs.writeFileSync(
-    triageFile,
-    JSON.stringify(
-      batch.map((d) => priority.get(d.url)).filter(Boolean),
-      null,
-      2,
-    ),
-  )
+  fs.writeFileSync(triageFile, JSON.stringify(batch.map((d) => priority.get(d.url)).filter(Boolean), null, 2))
 
   const prompt = `${basePrompt}
 
@@ -88,7 +82,21 @@ Batch specifics for this run: the PRs to handle are in the attached ${batchFile}
     // permission.bash map via KILO_CONFIG_CONTENT should replace --auto once the
     // required shell patterns are stable (see PR #12605 review thread).
     const result = runKilo({
-      args: ["run", "--auto", prompt, "-m", model, "--variant", "high", "--dir", process.cwd(), "-f", batchFile, "-f", triageFile],
+      args: [
+        "run",
+        "--auto",
+        prompt,
+        "-m",
+        model,
+        "--variant",
+        "high",
+        "--dir",
+        process.cwd(),
+        "-f",
+        batchFile,
+        "-f",
+        triageFile,
+      ],
       timeoutMs: Math.min(BATCH_TIMEOUT_MS, left),
       streamStdout: true,
       label: `edit batch ${index} attempt ${attempt}`,
@@ -120,9 +128,7 @@ Batch specifics for this run: the PRs to handle are in the attached ${batchFile}
         console.warn(`batch ${index}: backing off ${wait / 1000}s before attempt ${attempt + 1}`)
         sleepSync(wait)
       } else if (wait > 0) {
-        console.warn(
-          `batch ${index}: skipping backoff — remaining budget cannot fit attempt ${attempt + 1} after wait`,
-        )
+        console.warn(`batch ${index}: skipping backoff — remaining budget cannot fit attempt ${attempt + 1} after wait`)
       }
     }
   }
diff --git a/.github/docs-sync/learn.mjs b/.github/docs-sync/learn.mjs
new file mode 100644
index 00000000000..6baa59124e2
--- /dev/null
+++ b/.github/docs-sync/learn.mjs
@@ -0,0 +1,937 @@
+// kilocode_change - new file
+
+/**
+ * Learns general rules of thumb from maintainer corrections to the docs-sync
+ * bot's rolling pull request, and writes them into packages/kilo-docs/LEARNINGS.md
+ * so the triage and edit passes follow them on every subsequent run.
+ *
+ * Two modes:
+ *   node learn.mjs           — extraction: fetch corrections, call the model, validate
+ *   node learn.mjs --apply   — apply: write learnings.json into LEARNINGS.md
+ *
+ * Env: TRIAGE_MODEL (provider/model, reused), GH_TOKEN (or GITHUB_TOKEN).
+ * Budget: LEARNINGS_BUDGET_MINUTES (default 10).
+ * Test hook: DOCS_SYNC_FIXTURE. When set to a fixture JSON path, skips every
+ * GitHub API call and writes any marker PATCH to <fixture>.patched instead of
+ * the network. The workflow never sets it — only selftests do.
+ *
+ * Test hook: DOCS_SYNC_BACKOFF_MS replaces wait between extraction retries, same as
+ * lib.mjs:138 documents for triage.mjs and edit.mjs.
+ *
+ * Patch suppression: DRY_RUN=true or LEARNINGS_NO_PATCH=1 suppress the marker PATCH.
+ */
+
+import { execFileSync } from "node:child_process"
+import fs from "node:fs"
+import path from "node:path"
+import { fileURLToPath, pathToFileURL } from "node:url"
+
+const LEARNINGS_FILE = "packages/kilo-docs/LEARNINGS.md"
+const OUT_DIR = "docs-sync-out"
+const ATTEMPTS = 2
+const LEARNINGS_BUDGET_MINUTES = Number(process.env.LEARNINGS_BUDGET_MINUTES) || 10
+const EXTRACTION_TIMEOUT_MS = LEARNINGS_BUDGET_MINUTES * 60 * 1000
+const COMMENT_BODY_CAP = 5000
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+
+const LINE_RE =
+  /^- (?<rule>.+?) <!-- id=(?<id>[a-z0-9][a-z0-9-]{2,48}) scope=(?<scope>triage|edit|both) source=(?<source>commit:[0-9a-f]{7,40}|comment:\d+) date=(?<date>\d{4}-\d{2}-\d{2}) -->$/
+
+const LEARNED_THROUGH_RE = /<!--\s*docs-sync:\s*learned-through\s+commit=(\S+)\s+comment=(\S+)\s*-->/
+
+// Agent-generated strings land in the PR body next to machine-read markers.
+// Identical to clean() at upsert-pr.mjs:37.
+function clean(value) {
+  return String(value ?? "")
+    .replaceAll("<!--", "")
+    .replaceAll("-->", "")
+}
+
+function warn(msg) {
+  console.warn(`::warning::${msg}`)
+}
+
+function log(msg) {
+  console.log(msg)
+}
+
+// --- pure exports ---
+
+/**
+ * Parse the LEARNINGS.md file text into an entry array.
+ * Drops lines inside the markers that do not match the format.
+ */
+export function parseLearnings(text) {
+  const m = String(text ?? "").match(
+    /<!--\s*docs-sync:learnings:start\s*-->([\s\S]*?)<!--\s*docs-sync:learnings:end\s*-->/,
+  )
+  if (!m) return []
+  const entries = []
+  for (const line of m[1].split("\n")) {
+    const trimmed = line.trim()
+    if (!trimmed) continue
+    const parsed = trimmed.match(LINE_RE)
+    if (!parsed) {
+      warn(`LEARNINGS.md: dropping unparseable line: ${trimmed.slice(0, 80)}`)
+      continue
+    }
+    entries.push({
+      id: parsed.groups.id,
+      rule: clean(parsed.groups.rule).replaceAll("\n", " "),
+      scope: parsed.groups.scope,
+      source: parsed.groups.source,
+      date: parsed.groups.date,
+    })
+  }
+  return entries
+}
+
+/** Render the full LEARNINGS.md file text from an entry array. Deterministic order. */
+export function renderLearnings(entries) {
+  const list = [...entries].sort((a, b) => {
+    if (a.date !== b.date) return a.date < b.date ? -1 : 1
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0
+  })
+  const lines = list.map(
+    (e) =>
+      `- ${clean(e.rule).replaceAll("\n", " ")} <!-- id=${e.id} scope=${e.scope} source=${e.source} date=${e.date} -->`,
+  )
+  return [
+    "# docs-sync learnings",
+    "",
+    "Rules the docs-sync bot learned from maintainer corrections to its rolling pull request.",
+    "The bot reads this file at the start of every run and follows every rule below.",
+    "",
+    "To unlearn a rule, delete its line and commit. The next run reads this file from the",
+    "branch, so the rule is gone from its input, and the deletion itself is a correction the",
+    "extraction step is instructed not to undo.",
+    "",
+    "<!-- docs-sync:learnings:start -->",
+    ...lines,
+    "<!-- docs-sync:learnings:end -->",
+    "",
+  ].join("\n")
+}
+
+/** Parse the learned-through watermark from a PR body. Returns { commit, comment } with nulls for absent/none. */
+export function parseLearnedThrough(body) {
+  const m = String(body ?? "").match(LEARNED_THROUGH_RE)
+  if (!m) return { commit: null, comment: null }
+  const commit = m[1] === "none" ? null : m[1]
+  const comment = m[2] === "none" ? null : m[2]
+  return { commit, comment }
+}
+
+/** Render a single learned-through marker line. */
+export function renderLearnedThrough({ commit, comment }) {
+  const c = commit ?? "none"
+  const m = comment ?? "none"
+  return `<!-- docs-sync: learned-through commit=${c} comment=${m} -->`
+}
+
+/** Replace or append the learned-through marker in a PR body. Pure — no API call. */
+export function patchMarkerIntoBody(body, marker) {
+  const b = String(body ?? "")
+  if (LEARNED_THROUGH_RE.test(b)) {
+    return b.replace(LEARNED_THROUGH_RE, marker)
+  }
+  return b + "\n" + marker + "\n"
+}
+
+/**
+ * Extract { add, remove } from raw model stdout.
+ * Mirrors parseTriageEntries at extract-json.mjs:14-38, adapted for an object.
+ * `kilo run` prints the assistant message twice; the last copy wins.
+ * Walk "{" positions from right to left; return the first that parses to an object
+ * holding an array `add` or an array `remove`.
+ */
+export function parseDelta(raw) {
+  const r = String(raw ?? "")
+  const end = r.lastIndexOf("}")
+  if (end < 0) return null
+
+  const starts = []
+  for (let i = 0; i <= end; i++) {
+    if (r[i] === "{") starts.push(i)
+  }
+
+  for (let s = starts.length - 1; s >= 0; s--) {
+    let parsed
+    try {
+      parsed = JSON.parse(r.slice(starts[s], end + 1))
+    } catch {
+      continue
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) continue
+    if (Array.isArray(parsed.add) || Array.isArray(parsed.remove)) {
+      return {
+        add: Array.isArray(parsed.add) ? parsed.add : [],
+        remove: Array.isArray(parsed.remove) ? parsed.remove : [],
+      }
+    }
+  }
+  return null
+}
+
+/** Cap a review comment body so a single long comment cannot dominate extraction input. */
+function capBody(body) {
+  const b = String(body ?? "")
+  if (b.length <= COMMENT_BODY_CAP) return b
+  return b.slice(0, COMMENT_BODY_CAP) + " [truncated]"
+}
+
+/** Normalize rule text for duplicate comparison: lowercase, strip punctuation and whitespace runs. */
+function norm(text) {
+  return String(text ?? "")
+    .toLowerCase()
+    .replace(/[^\w\s]/g, "")
+    .replace(/\s+/g, " ")
+    .trim()
+}
+
+/**
+ * Validate a delta against the existing entries and constraints.
+ * Returns { add, remove, rejected }. Never throws.
+ */
+export function validateDelta(delta, { existing, candidateSources, deletedInWindow }) {
+  const add = Array.isArray(delta.add) ? delta.add : []
+  const remove = Array.isArray(delta.remove) ? delta.remove : []
+  const ex = Array.isArray(existing) ? existing : []
+  const candidates = Array.isArray(candidateSources) ? candidateSources : []
+  const deleted = Array.isArray(deletedInWindow) ? deletedInWindow : []
+
+  const rejected = []
+  const valid = []
+  const toRemove = []
+  const existingIds = new Set(ex.map((e) => e.id))
+  // One model response can repeat an id or a rule. Both would render two lines for
+  // one id, so an accepted addition also blocks the next one.
+  const acceptedIds = new Set()
+  const acceptedRules = new Set()
+
+  // Process remove first so toRemove is populated before the add loop checks
+  // for id collisions with entries listed in remove (criterion 8).
+  for (const id of remove) {
+    if (!existingIds.has(id)) {
+      rejected.push({ entry: { id, remove: id }, reason: `remove target ${id} not in existing entries` })
+    } else {
+      toRemove.push(id)
+    }
+  }
+
+  for (const a of add) {
+    let reason = null
+
+    // Reject null, undefined, and non-object entries before any property access.
+    if (a === null || a === undefined || typeof a !== "object" || Array.isArray(a)) {
+      rejected.push({ entry: a, reason: "add entry is null, undefined, or not a plain object" })
+      continue
+    }
+
+    if (!a.rule || String(a.rule).length < 10 || String(a.rule).length > 300) {
+      reason = "rule text absent, shorter than 10 characters, or longer than 300"
+    } else if (!["triage", "edit", "both"].includes(a.scope)) {
+      reason = `invalid scope: ${a.scope}`
+    } else if (!/^commit:[0-9a-f]{7,40}$/.test(a.source) && !/^comment:\d+$/.test(a.source)) {
+      reason = `invalid source format: ${a.source}`
+    } else if (!candidates.includes(a.source)) {
+      reason = `source ${a.source} not in candidate sources`
+    } else if (!/^[a-z0-9][a-z0-9-]{2,48}$/.test(a.id)) {
+      reason = `invalid id format: ${a.id}`
+    } else if (existingIds.has(a.id) && !toRemove.includes(a.id)) {
+      reason = `id ${a.id} collides with an existing entry not listed in remove`
+    } else if (acceptedIds.has(a.id)) {
+      reason = `id ${a.id} collides with an earlier addition in this delta`
+    } else if (!/^\d{4}-\d{2}-\d{2}$/.test(a.date)) {
+      reason = `invalid date format: ${a.date}`
+    } else {
+      // Check that date is a real calendar date.
+      const d = new Date(a.date + "T00:00:00Z")
+      if (Number.isNaN(d.getTime()) || d.toISOString().slice(0, 10) !== a.date) {
+        reason = `invalid calendar date: ${a.date}`
+      }
+    }
+
+    if (reason) {
+      rejected.push({ entry: a, reason })
+      continue
+    }
+
+    const n = norm(a.rule)
+
+    // Duplicate of an existing entry not being removed.
+    if (ex.some((e) => norm(e.rule) === n && !remove.includes(e.id))) {
+      reason = `rule text is a duplicate of an existing entry not listed in remove`
+      rejected.push({ entry: a, reason })
+      continue
+    }
+
+    // Duplicate of an earlier addition in the same response.
+    if (acceptedRules.has(n)) {
+      reason = `rule text is a duplicate of an earlier addition in this delta`
+      rejected.push({ entry: a, reason })
+      continue
+    }
+
+    // Names a PR, URL, person, or docs page. The URL clause keeps docs-check-links.yml green.
+    if (String(a.rule).match(/#\d{2,}|https?:\/\/|@[A-Za-z0-9-]|packages\/kilo-docs|\.md\b/)) {
+      reason = "rule names a PR, URL, person, or docs page"
+      rejected.push({ entry: a, reason })
+      continue
+    }
+
+    // Duplicate of a rule deleted in this window.
+    if (deleted.some((d) => norm(d) === n)) {
+      reason = "rule text matches a line a maintainer deleted in this window"
+      rejected.push({ entry: a, reason })
+      continue
+    }
+
+    acceptedIds.add(a.id)
+    acceptedRules.add(n)
+    valid.push({
+      id: a.id,
+      rule: clean(String(a.rule)).replaceAll("\n", " "),
+      scope: a.scope,
+      source: a.source,
+      date: a.date,
+    })
+  }
+
+  return { add: valid, remove: toRemove, rejected }
+}
+
+/** Apply a validated delta to an existing entry array. Drops removed ids, appends adds. */
+export function applyDelta(existing, delta) {
+  const ex = Array.isArray(existing) ? existing : []
+  const remove = new Set(Array.isArray(delta.remove) ? delta.remove : [])
+  const add = Array.isArray(delta.add) ? delta.add : []
+  return [...ex.filter((e) => !remove.has(e.id)), ...add]
+}
+
+/** Trust a review comment whose author_association is OWNER, MEMBER, or COLLABORATOR and is not a bot. */
+export function isTrustedComment(comment) {
+  if (!comment) return false
+  const login = String(comment.user?.login ?? "")
+  if (login.endsWith("[bot]")) return false
+  return ["OWNER", "MEMBER", "COLLABORATOR"].includes(comment.author_association)
+}
+
+/** Render the prompt block for a given scope. Returns "" when no entry matches. */
+export function promptBlock(entries, scope) {
+  const matches = (Array.isArray(entries) ? entries : []).filter((e) => e.scope === scope || e.scope === "both")
+  if (matches.length === 0) return ""
+  return [
+    "## Learnings from maintainer corrections",
+    "",
+    "Follow every rule below. Each was extracted from a correction a maintainer made to an",
+    "earlier run of this bot. A rule here outranks a general instruction above when they conflict.",
+    "",
+    ...matches.map((e) => `- ${e.rule}`),
+  ].join("\n")
+}
+
+/** Read a prompt block artifact from docs-sync-out. Returns the content or "" when absent. */
+export function readLearningsBlock(scope) {
+  const file = `${OUT_DIR}/learnings-${scope}.md`
+  try {
+    return fs.readFileSync(file, "utf8")
+  } catch {
+    return ""
+  }
+}
+
+// --- helpers for main ---
+
+function git(args) {
+  return execFileSync("git", args, { stdio: ["ignore", "pipe", "inherit"] })
+    .toString()
+    .trim()
+}
+
+// --- main ---
+
+async function main() {
+  // Step 0: ensure docs-sync-out exists. collect.mjs:139 is the only other unconditional
+  // mkdirSync of this directory, and it runs after the learn step. Without this line the
+  // empty-candidate path throws ENOENT on its first write, continue-on-error swallows it,
+  // and the feature silently never works.
+  fs.mkdirSync(OUT_DIR, { recursive: true })
+
+  if (process.argv.includes("--apply")) {
+    await apply()
+    return
+  }
+
+  await extract()
+}
+
+// --- apply mode ---
+
+async function apply() {
+  const learningsPath = `${OUT_DIR}/learnings.json`
+  if (!fs.existsSync(learningsPath)) {
+    log("learnings.json absent — extraction was skipped or failed; nothing to apply")
+    return
+  }
+  const entries = JSON.parse(fs.readFileSync(learningsPath, "utf8"))
+  const file = renderLearnings(entries)
+  fs.writeFileSync(LEARNINGS_FILE, file)
+  log(`wrote ${LEARNINGS_FILE} with ${entries.length} entries`)
+}
+
+// --- extraction mode ---
+
+async function extract() {
+  // Step 0: seed the prompt artifacts from the checked-out file before any fallible
+  // work. Every later step can throw, the workflow step is continue-on-error, and
+  // triage and edit read only these two files. Without the seed one failed API call
+  // silently drops every learned rule for the whole run. Later steps replace them
+  // with the rolling-branch copy and then with the validated delta.
+  writePromptArtifacts(parseLearnings(readFileOrEmpty(LEARNINGS_FILE)))
+
+  // Load fixture when DOCS_SYNC_FIXTURE is set.
+  const fixturePath = process.env.DOCS_SYNC_FIXTURE
+  let fixture = null
+  let patchFile = null
+  if (fixturePath) {
+    fixture = JSON.parse(fs.readFileSync(fixturePath, "utf8"))
+    patchFile = fixturePath + ".patched"
+  }
+
+  const { api, repo, searchIssues, appendOutput, appendSummary, backoffMsForAttempt, runKilo, sleepSync } =
+    await import("./lib.mjs")
+
+  let prData
+  let prBody = ""
+  let prNumber = ""
+  let branch = ""
+
+  if (fixture) {
+    // Fixture mode: skip all API calls.
+    prData = fixture.pr
+    prBody = prData.body ?? ""
+    prNumber = String(prData.number ?? 1)
+    branch = prData.head?.ref ?? "docs/auto-sync"
+  } else {
+    // Step 1: resolve the rolling PR. Use prepare-branch.mjs's selection rule so both
+    // target the same branch. searchIssues takes prs[0] with no author filter (like
+    // prepare-branch.mjs:69). But trust the body marker only when authored by
+    // github-actions[bot] (like watermark.mjs:35). The two rules differ on purpose:
+    // the branch must match what prepare-branch.mjs will check out, but a body is
+    // editable so its marker needs the author filter.
+    const r = repo()
+    const prs = await searchIssues(`repo:${r} is:pr is:open label:auto-docs sort:created-desc`, { maxPages: 1 })
+    if (prs.length === 0) {
+      log("no open rolling pull request — nothing to learn from")
+
+      // Read existing learnings from main for empty-state artifacts.
+      let existing = []
+      try {
+        const existingText = git(["show", `origin/main:${LEARNINGS_FILE}`])
+        existing = parseLearnings(existingText)
+      } catch {
+        existing = []
+      }
+      log(`no-PR existing entries from main: ${existing.length}`)
+      writeEmptyStateArtifacts(existing)
+      appendOutput("count", String(existing.length))
+      appendSummary("### docs-sync learnings\n\nNo open auto-docs pull request; extraction skipped.")
+      return
+    }
+    prData = await api(`/repos/${r}/pulls/${prs[0].number}`)
+    prBody = prData.body ?? ""
+    prNumber = String(prData.number)
+    branch = prData.head?.ref ?? "docs/auto-sync"
+  }
+
+  // Step 2: read existing entries.
+  let existing = []
+  let existingText = ""
+  if (fixture) {
+    existingText = readFileOrEmpty(LEARNINGS_FILE)
+    existing = parseLearnings(existingText)
+  } else {
+    try {
+      existingText = git(["show", `origin/${branch}:${LEARNINGS_FILE}`])
+    } catch {
+      // branch copy absent — fall back to main, then empty.
+      // Required for the first live run: the rolling branch predates the seeded file.
+      try {
+        existingText = git(["show", `origin/main:${LEARNINGS_FILE}`])
+      } catch {
+        existingText = ""
+      }
+    }
+    existing = parseLearnings(existingText)
+  }
+  log(`existing entries: ${existing.length}`)
+
+  // Replace the seed with the rolling-branch copy. Every step below can throw, and
+  // these two files are all triage and edit read.
+  writePromptArtifacts(existing)
+
+  // Step 3: parse marker. Trust only when authored by github-actions[bot] (like watermark.mjs:35).
+  let commitWm = null
+  let commentWm = null
+  const trusted = prData.user?.login === "github-actions[bot]"
+  if (trusted) {
+    ;({ commit: commitWm, comment: commentWm } = parseLearnedThrough(prBody))
+  } else {
+    log("PR author is not github-actions[bot]; ignoring body marker")
+  }
+  log(`watermark: commit=${commitWm ?? "none"} comment=${commentWm ?? "none"}`)
+
+  // Step 4: fetch and tip SHA.
+  let tipSha
+  if (fixture) {
+    tipSha = git(["rev-parse", "HEAD"])
+  } else {
+    git(["fetch", "origin", "main", branch])
+    tipSha = git(["rev-parse", `origin/${branch}`])
+  }
+
+  // Step 5: candidate commits.
+  let rangeArgs = [`origin/main..origin/${branch}`]
+  if (fixture) {
+    // In fixture mode, work from the local repo state.
+    try {
+      git(["rev-parse", "--verify", branch])
+      rangeArgs = [`origin/main..${branch}`]
+    } catch {
+      rangeArgs = [`origin/main..HEAD`]
+    }
+  }
+
+  if (commitWm) {
+    let wmExists = false
+    try {
+      git(["cat-file", "-e", `${commitWm}^{commit}`])
+      wmExists = true
+    } catch {
+      wmExists = false
+    }
+    if (wmExists) {
+      rangeArgs.push(`^${commitWm}`)
+    }
+    // A missing watermark commit (force-push, rebase) drops the exclusion.
+    // The duplicate-rule-text rejection in validateDelta blocks the re-added duplicate.
+  }
+
+  const logOut = git(["log", "--no-merges", "--format=%H|%ae|%cI|%s", ...rangeArgs])
+  const rawCommits = logOut ? logOut.split("\n").filter(Boolean) : []
+
+  const botEmail = "41898282+github-actions[bot]@users.noreply.github.com"
+  const candidates = []
+  const candidateSources = []
+  const deletedInWindow = []
+
+  for (const line of rawCommits) {
+    const [sha, email, dateIso] = line.split("|")
+    // Drop commits authored by the sync job itself (criterion 5).
+    if (email === botEmail) continue
+    // Everything reachable from main is already excluded by the range (criterion 6).
+
+    // Get the full file list.
+    let files = []
+    try {
+      const out = git(["show", "--name-only", "--format=", sha])
+      files = out
+        ? out
+            .split("\n")
+            .filter(Boolean)
+            .filter((f) => f)
+        : []
+    } catch {
+      continue
+    }
+
+    // Get the docs-scoped diff and message.
+    let message = ""
+    let docDiff = ""
+    try {
+      message = git(["show", "--format=%B", "--no-patch", sha]).trim()
+      docDiff = git(["show", "--format=", sha, "--", "packages/kilo-docs"])
+      // Cap diff sizes.
+      if (docDiff.length > 20000) docDiff = docDiff.slice(0, 20000) + "\n[truncated]"
+    } catch {
+      // skip on error
+    }
+
+    // Drop commits whose docs-scoped diff is empty.
+    if (!docDiff.trim()) continue
+
+    // Collect deleted rule lines from LEARNINGS.md.
+    for (const dl of docDiff.split("\n")) {
+      if (!dl.startsWith("-")) continue
+      const stripped = dl.slice(1).trim()
+      const parsed = stripped.match(LINE_RE)
+      if (parsed) {
+        deletedInWindow.push(clean(parsed.groups.rule).replaceAll("\n", " "))
+      }
+    }
+
+    // Cap total diff data.
+    const totalDiff = candidates.reduce((n, c) => n + (c.diff ? c.diff.length : 0), 0)
+    if (totalDiff > 120000) {
+      log(`diff cap reached at commit ${sha.slice(0, 7)}; truncating`)
+      candidates.push({
+        source: `commit:${sha.slice(0, 7)}`,
+        iso: dateIso,
+        date: dateIso.slice(0, 10),
+        message,
+        files,
+        diff: "[truncated]",
+      })
+      candidateSources.push(`commit:${sha.slice(0, 7)}`)
+      break
+    }
+
+    candidates.push({
+      source: `commit:${sha.slice(0, 7)}`,
+      iso: dateIso,
+      date: dateIso.slice(0, 10),
+      message,
+      files,
+      diff: docDiff,
+    })
+    candidateSources.push(`commit:${sha.slice(0, 7)}`)
+  }
+
+  // Step 6: candidate comments.
+  let allComments = []
+  let maxCommentAt = "none"
+
+  if (fixture && fixture.comments) {
+    allComments = fixture.comments
+  } else if (prNumber) {
+    const pages = []
+    for (let page = 1; page <= 5; page++) {
+      const batch = await api(`/repos/${repo()}/pulls/${prNumber}/comments?per_page=100&page=${page}`)
+      pages.push(...batch)
+      if (batch.length < 100) break
+    }
+    allComments = pages
+  }
+
+  if (allComments.length > 0) {
+    let max = ""
+    for (const c of allComments) {
+      if (c.created_at && c.created_at > max) max = c.created_at
+    }
+    maxCommentAt = max || "none"
+  }
+
+  // Filter trusted comments.
+  const trustedComments = allComments.filter((c) => {
+    if (!isTrustedComment(c)) return false
+    if (commentWm && c.created_at <= commentWm) return false
+    return true
+  })
+
+  // Step 7: correlate comments to commits.
+  // A comment is a commit's trigger when c.path is in that commit's full file list
+  // and c.created_at < commit date. The earliest such commit claims it.
+  // Compare parsed timestamps so different timezone offsets do not skew the ordering.
+  for (const c of trustedComments) {
+    let best = null
+    const cTime = Date.parse(c.created_at)
+    for (const cc of candidates) {
+      if (!Array.isArray(cc.files) || !cc.files.includes(c.path)) continue
+      const ccTime = Date.parse(cc.iso)
+      if (cTime < ccTime) {
+        if (!best || ccTime < Date.parse(best.iso)) {
+          best = cc
+        }
+      }
+    }
+    if (best) {
+      best.comment = {
+        author_association: c.author_association,
+        path: c.path,
+        body: capBody(c.body),
+      }
+    } else {
+      candidates.push({
+        source: `comment:${c.id}`,
+        date: (c.created_at ?? "").slice(0, 10),
+        path: c.path,
+        body: capBody(c.body),
+        author_association: c.author_association,
+      })
+      candidateSources.push(`comment:${c.id}`)
+    }
+  }
+
+  // Step 8: no candidates → empty delta route.
+  const hasCandidates = candidates.length > 0
+
+  if (!hasCandidates) {
+    log("no candidate corrections; advancing marker with no model call")
+    writeEmptyStateArtifacts(existing)
+    appendOutput("count", String(existing.length))
+    appendSummary(
+      `### docs-sync learnings\n\nNo new candidate corrections. Entries: ${existing.length}. Marker route: empty (no candidates).`,
+    )
+
+    const marker = renderLearnedThrough({ commit: tipSha, comment: maxCommentAt })
+    await patchOrLogMarker({ prBody, prNumber, marker, fixture, patchFile })
+    return
+  }
+
+  // Step 9: write learnings input.
+  const input = {
+    existing: existing.map((e) => ({ id: e.id, rule: e.rule, scope: e.scope, source: e.source, date: e.date })),
+    deleted_in_window: deletedInWindow,
+    corrections: candidates,
+  }
+  const inputFile = `${OUT_DIR}/learnings-input.json`
+  fs.writeFileSync(inputFile, JSON.stringify(input, null, 2))
+  log(`wrote ${inputFile} with ${candidates.length} candidates`)
+
+  // Step 10: call the model.
+  // Deliberately no --auto. Every input is in the attached file and the output goes to
+  // stdout, so the agent needs no tool. Omitting --auto makes "the extraction step never
+  // writes outside LEARNINGS.md" structurally true instead of prompt-deep. triage.mjs:76
+  // and edit.mjs:86 carry the opposite comment; do not copy them without updating the reason.
+  const prompt = fs.readFileSync(path.join(HERE, "learnings-prompt.md"), "utf8")
+  const model = process.env.TRIAGE_MODEL
+  if (!model) throw new Error("TRIAGE_MODEL is required")
+
+  const budgetDeadline = Date.now() + EXTRACTION_TIMEOUT_MS
+
+  let raw = null
+  let lastCause = "extraction failed"
+
+  for (let attempt = 1; attempt <= ATTEMPTS; attempt++) {
+    const left = Math.max(0, budgetDeadline - Date.now())
+    if (left <= 0) {
+      log("budget exhausted before extraction attempt")
+      break
+    }
+
+    const result = runKilo({
+      args: ["run", prompt, "-m", model, "--dir", process.cwd(), "-f", inputFile],
+      timeoutMs: Math.min(EXTRACTION_TIMEOUT_MS, left),
+      streamStdout: false,
+      label: "learnings extraction",
+    })
+
+    if (result.stdout) {
+      fs.writeFileSync(`${OUT_DIR}/learnings-raw.txt`, result.stdout)
+      raw = result.stdout
+      const delta = parseDelta(raw)
+      if (delta) break
+      lastCause = `parseDelta returned null (attempt ${attempt})`
+    } else {
+      lastCause = result.timedOut ? "timed out" : `exit ${result.exitCode}`
+    }
+
+    if (attempt < ATTEMPTS) {
+      const wait = backoffMsForAttempt(1) // 60s, same as the sibling convention
+      if (wait > 0) {
+        log(`backing off ${wait / 1000}s before attempt ${attempt + 1}`)
+        sleepSync(wait)
+      }
+    }
+  }
+
+  // Step 11: parse and validate.
+  const delta = raw ? parseDelta(raw) : null
+
+  if (!delta) {
+    // parseDelta null after every try — retryable unhappy.
+    warn(`extraction failed: ${lastCause}. Leaving learnings untouched.`)
+    writeEmptyStateArtifacts(existing)
+    appendOutput("count", String(existing.length))
+    appendSummary(
+      `### docs-sync learnings\n\nExtraction failed: ${lastCause}. Entries unchanged: ${existing.length}. No marker advance.`,
+    )
+    return
+  }
+
+  const validated = validateDelta(delta, { existing, candidateSources, deletedInWindow })
+
+  if (validated.rejected.length > 0) {
+    for (const r of validated.rejected) {
+      warn(`rejected: ${r.reason}` + (r.entry?.id ? ` (id=${r.entry.id})` : ""))
+    }
+  }
+
+  const nonEmpty = validated.add.length > 0 || validated.remove.length > 0
+
+  // Step 12: route by outcome (G5 table, exact).
+  if (nonEmpty) {
+    // Non-empty validated delta.
+    const newEntries = applyDelta(existing, { add: validated.add, remove: validated.remove })
+    fs.writeFileSync(`${OUT_DIR}/learnings.json`, JSON.stringify(newEntries, null, 2))
+    const marker = renderLearnedThrough({ commit: tipSha, comment: maxCommentAt })
+    const suppressed = process.env.DRY_RUN === "true" || process.env.LEARNINGS_NO_PATCH === "1"
+    if (!suppressed) appendOutput("learned_through", marker)
+    if (suppressed) log(`learned-through output suppressed: ${marker}`)
+
+    const added = validated.add.length
+    const removed = validated.remove.length
+    const rejected = validated.rejected.length
+    log(`delta: +${added} -${removed} (${rejected} rejected)`)
+    appendSummary(
+      `### docs-sync learnings\n\n- added: ${added}\n- removed: ${removed}\n- rejected: ${rejected}\n- candidates: ${candidates.length}\n- marker route: upsert (non-empty delta)\n`,
+    )
+
+    writePromptArtifacts(newEntries)
+    appendOutput("count", String(newEntries.length))
+
+    // Marker rides through LEARNED_THROUGH into upsert-pr.mjs. No direct PATCH.
+  } else {
+    // Empty validated delta (nothing added, nothing removed, including every-add-rejected).
+    log("empty validated delta; advancing marker directly")
+    fs.writeFileSync(`${OUT_DIR}/learnings.json`, JSON.stringify(existing, null, 2))
+    writePromptArtifacts(existing)
+    appendOutput("count", String(existing.length))
+
+    const marker = renderLearnedThrough({ commit: tipSha, comment: maxCommentAt })
+    await patchOrLogMarker({ prBody, prNumber, marker, fixture, patchFile })
+
+    const rejected = validated.rejected.length
+    appendSummary(
+      `### docs-sync learnings\n\n- added: 0\n- removed: 0\n- rejected: ${rejected}\n- candidates: ${candidates.length}\n- marker route: direct PATCH (empty delta)\n`,
+    )
+  }
+}
+
+// --- shared helpers ---
+
+function writeEmptyStateArtifacts(entries) {
+  fs.writeFileSync(`${OUT_DIR}/learnings.json`, JSON.stringify(entries, null, 2))
+  writePromptArtifacts(entries)
+}
+
+// A later call must be able to shrink a seeded block back to nothing, so an empty
+// block removes the file instead of leaving the earlier content in place.
+function writePromptArtifacts(entries) {
+  writeOrRemove(`${OUT_DIR}/learnings-triage.md`, promptBlock(entries, "triage"))
+  writeOrRemove(`${OUT_DIR}/learnings-edit.md`, promptBlock(entries, "edit"))
+}
+
+function writeOrRemove(file, text) {
+  if (text) fs.writeFileSync(file, text)
+  else fs.rmSync(file, { force: true })
+}
+
+function readFileOrEmpty(file) {
+  try {
+    return fs.readFileSync(file, "utf8")
+  } catch {
+    return ""
+  }
+}
+
+async function patchOrLogMarker({ prBody, prNumber, marker, fixture, patchFile }) {
+  const suppressed = process.env.DRY_RUN === "true" || process.env.LEARNINGS_NO_PATCH === "1"
+
+  if (suppressed) {
+    log(
+      `marker PATCH suppressed (DRY_RUN=${process.env.DRY_RUN}, LEARNINGS_NO_PATCH=${process.env.LEARNINGS_NO_PATCH})`,
+    )
+    log(`would have written marker: ${marker}`)
+    return
+  }
+
+  if (fixture) {
+    // Write to the fixture patch file instead of the network.
+    fs.writeFileSync(patchFile, marker)
+    log(`wrote marker to ${patchFile}`)
+    return
+  }
+
+  // Live PATCH: body-only, one line changed. The job already holds pull-requests: write.
+  // Re-read the body first. The body in hand was fetched before the extraction call, so
+  // patching that copy would drop any edit made in the minutes since. GitHub has no
+  // conditional update for a pull request body, so a short fetch-to-PATCH race remains.
+  const { api, repo } = await import("./lib.mjs")
+  let latestBody = prBody
+  try {
+    const fresh = await api(`/repos/${repo()}/pulls/${prNumber}`)
+    latestBody = fresh.body ?? ""
+  } catch (err) {
+    warn(`could not re-read PR #${prNumber} before the marker PATCH: ${err.message}. Using the earlier body.`)
+  }
+  const newBody = patchMarkerIntoBody(latestBody, marker)
+  await api(`/repos/${repo()}/pulls/${prNumber}`, {
+    method: "PATCH",
+    body: { body: newBody },
+  })
+  log(`PATCHed learned-through marker on PR #${prNumber}`)
+}
+
+// --- entry point ---
+
+const isMain = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href
+
+// --- self-test harness (run: node .github/docs-sync/learn.mjs --self-test) ---
+if (isMain && process.argv.includes("--self-test")) {
+  const failures = []
+  const check = (label, fn) => {
+    try {
+      const ok = fn()
+      if (!ok) failures.push(label)
+    } catch (e) {
+      failures.push(label + " THREW: " + e.message)
+    }
+  }
+
+  check("null in add does not throw", () => {
+    const r = validateDelta({ add: [null], remove: [] }, { existing: [], candidateSources: [], deletedInWindow: [] })
+    return r.add.length === 0 && r.rejected.length === 1 && r.rejected[0].reason.includes("not a plain object")
+  })
+
+  check("undefined in add does not throw", () => {
+    const r = validateDelta(
+      { add: [undefined], remove: [] },
+      { existing: [], candidateSources: [], deletedInWindow: [] },
+    )
+    return r.add.length === 0 && r.rejected.length === 1 && r.rejected[0].reason.includes("not a plain object")
+  })
+
+  check("mixed valid and null retains valid", () => {
+    const r = validateDelta(
+      {
+        add: [
+          {
+            id: "valid-a",
+            rule: "Do not document experimental features",
+            scope: "both",
+            source: "commit:bbbbbbb",
+            date: "2026-08-03",
+          },
+          null,
+          {
+            id: "valid-b",
+            rule: "Keep release notes concise",
+            scope: "edit",
+            source: "commit:bbbbbbb",
+            date: "2026-08-03",
+          },
+        ],
+        remove: [],
+      },
+      { existing: [], candidateSources: ["commit:bbbbbbb"], deletedInWindow: [] },
+    )
+    return r.add.length === 2 && r.rejected.length === 1
+  })
+
+  if (failures.length) {
+    console.error("SELF-TEST FAILURES:", failures)
+    process.exit(1)
+  }
+  console.log("SELF-TEST PASSED (" + 3 + " checks)")
+  process.exit(0)
+}
+
+if (isMain) {
+  main().catch((err) => {
+    console.error(err)
+    process.exit(1)
+  })
+}
diff --git a/.github/docs-sync/learnings-prompt.md b/.github/docs-sync/learnings-prompt.md
new file mode 100644
index 00000000000..cde193b8d4f
--- /dev/null
+++ b/.github/docs-sync/learnings-prompt.md
@@ -0,0 +1,84 @@
+You are the extraction pass of an automated documentation pipeline for Kilo Code. Your only job: extract general rules of thumb from maintainer corrections to the docs-sync bot's rolling pull request. A correction is a commit or review comment a maintainer made to fix something the bot got wrong, and a learning is the general principle behind it that the bot should follow from now on.
+
+The attached `learnings-input.json` file contains:
+
+- `existing`: rules the bot already knows, each with `id`, `rule`, `scope`, `source`, and `date`.
+- `deleted_in_window`: rule texts (not ids) a maintainer deleted from the learnings file in this extraction window. A maintainer deleted these on purpose — do not re-add them.
+- `corrections`: the maintainer corrections to learn from. Each entry has a `source` (commit or comment id), `date`, and the relevant context. Commit entries have `message`, `files`, and `diff`. Comment entries have `path` and `body`. Some commits also carry an attached inline review `comment` that triggered them.
+
+Before writing anything:
+
+1. Read every correction in `corrections` and every rule in `existing`.
+2. For each correction, decide whether it implies a general rule of thumb the bot should follow. Not every correction does — returning no new rules is a valid and expected answer.
+3. When a correction implies a rule, write it as one imperative sentence stating the general principle, not what the specific correction did.
+
+Response format: a strict JSON object with no prose, no markdown fences, no comments:
+
+```json
+{
+  "add": [
+    {
+      "id": "kebab-case-slug",
+      "rule": "One imperative sentence.",
+      "scope": "triage|edit|both",
+      "source": "commit:<sha>|comment:<id>",
+      "date": "<yyyy-mm-dd>"
+    }
+  ],
+  "remove": []
+}
+```
+
+- `id`: a short kebab-case slug unique across this response.
+- `rule`: one general imperative sentence. Never name a pull request, a number, a URL, a docs page, a file path, or a person. State the rule the correction implies, not what the correction changed.
+- `scope`: `triage` when the rule changes which pull requests deserve documentation; `edit` when it changes how a page is written; `both` when it changes both.
+- `source`: copied verbatim from the correction's `source` field. Never invent one.
+- `date`: the correction's date, copied verbatim.
+
+The `remove` array lists `id` values of existing entries to drop. Remove an id only when a new rule contradicts or supersedes it.
+
+Hard rules:
+
+- The list of `add` entries may be empty. Returning `{"add": [], "remove": []}` is a valid and expected answer when no correction implies a general rule.
+- Never re-add a rule listed in `deleted_in_window`, and never add a reworded near-duplicate of one. A maintainer deleted it.
+- When a new rule is a near-duplicate of an existing one, merge them into one `add` and list the old id in `remove`.
+- When a new rule contradicts an existing rule, `add` the new one and `remove` the contradicted id.
+- Every `add` entry must have a `source` that appears in the input's `corrections` list. Never invent a source.
+- Do not read files and do not run commands. Every input is already attached.
+
+Example. Input:
+
+```json
+{
+  "existing": [],
+  "deleted_in_window": [],
+  "corrections": [
+    {
+      "source": "commit:9dd2c07",
+      "date": "2026-08-03",
+      "message": "docs: remove experimental features page",
+      "files": ["packages/kilo-docs/pages/code-with-ai/experimental-features.md"],
+      "diff": "- removed the entire experimental features page\n- the page documented features behind unreleased flags"
+    }
+  ]
+}
+```
+
+Expected output:
+
+```json
+{
+  "add": [
+    {
+      "id": "no-experimental-features",
+      "rule": "Do not document features that are behind unreleased flags.",
+      "scope": "both",
+      "source": "commit:9dd2c07",
+      "date": "2026-08-03"
+    }
+  ],
+  "remove": []
+}
+```
+
+The rule is `both` because documenting unreleased features is wrong at triage time (the feature is not docs-worthy yet) and at edit time (the page should not exist).
diff --git a/.github/docs-sync/lib.mjs b/.github/docs-sync/lib.mjs
index 6aaf9dc6c36..f63155adf66 100644
--- a/.github/docs-sync/lib.mjs
+++ b/.github/docs-sync/lib.mjs
@@ -9,7 +9,9 @@
 import { spawnSync } from "node:child_process"
 import fs from "node:fs"
 
-const API = "https://api.github.com"
+// Test hook: DOCS_SYNC_API_BASE points the API at a local stub server. The workflow
+// never sets it — only selftests do.
+const API = process.env.DOCS_SYNC_API_BASE || "https://api.github.com"
 const MAX_RETRIES = 3
 
 export function token() {
diff --git a/.github/docs-sync/selftest.mjs b/.github/docs-sync/selftest.mjs
index 9af35c58cdf..8341b0ef9ad 100644
--- a/.github/docs-sync/selftest.mjs
+++ b/.github/docs-sync/selftest.mjs
@@ -7,12 +7,13 @@
  */
 
 import assert from "node:assert/strict"
-import { execFileSync, spawnSync } from "node:child_process"
+import { execFileSync, spawn, spawnSync } from "node:child_process"
 import fs from "node:fs"
 import os from "node:os"
 import path from "node:path"
 import { fileURLToPath } from "node:url"
 
+import { sleepSync } from "./lib.mjs"
 import { mergeOrFallback, DEFAULT_BRANCH } from "./prepare-branch.mjs"
 import { applyCap } from "./watermark.mjs"
 import {
@@ -21,6 +22,9 @@ import {
   routeRows,
   dropLegacySkipped,
   noDiffReport,
+  LEARNINGS_FILE,
+  nonContentFiles,
+  resolveLearnedThrough,
   renderBody,
   extractSectionRows,
 } from "./upsert-pr.mjs"
@@ -31,11 +35,23 @@ import {
   applyRevertAnnotations,
   unannotatedRevertSignals,
 } from "./reverts.mjs"
+import {
+  parseLearnings,
+  renderLearnings,
+  parseLearnedThrough,
+  patchMarkerIntoBody,
+  parseDelta,
+  validateDelta,
+  applyDelta,
+  isTrustedComment,
+  promptBlock,
+} from "./learn.mjs"
 
 const HERE = path.dirname(fileURLToPath(import.meta.url))
 const EDIT_SCRIPT = path.join(HERE, "edit.mjs")
 const TRIAGE_SCRIPT = path.join(HERE, "triage.mjs")
 const COLLECT_SCRIPT = path.join(HERE, "collect.mjs")
+const LEARN_SCRIPT = path.join(HERE, "learn.mjs")
 
 const temps = []
 
@@ -154,6 +170,16 @@ if (mode === "triage-embed-env-secret") {
   process.stdout.write(JSON.stringify(entries) + "\\n");
   process.exit(0);
 }
+if (mode === "extraction-delta") {
+  const deltaFile = "docs-sync-out/extraction-delta.json";
+  if (fs.existsSync(deltaFile)) {
+    const delta = JSON.parse(fs.readFileSync(deltaFile, "utf8"));
+    process.stdout.write(JSON.stringify(delta) + "\\n");
+  } else {
+    process.stdout.write('{"add":[],"remove":[]}' + "\\n");
+  }
+  process.exit(0);
+}
 process.stderr.write("unknown stub mode\\n");
 process.exit(1);
 `
@@ -321,9 +347,9 @@ function setupTriageCwd(digest) {
   return cwd
 }
 
-function runNodeScript(scriptPath, { cwd, env = {}, kiloDir }) {
+function runNodeScript(scriptPath, { cwd, env = {}, kiloDir, args = [] }) {
   const pathEnv = [kiloDir, process.env.PATH].filter(Boolean).join(path.delimiter)
-  const result = spawnSync(process.execPath, [scriptPath], {
+  const result = spawnSync(process.execPath, [scriptPath, ...args], {
     cwd,
     env: {
       ...process.env,
@@ -1067,10 +1093,12 @@ function case4_routing() {
 
   // round-trip renderBody → extractSectionRows
   const through = "2026-07-20T09:59:59.999Z"
+  const learnedMarker = "<!-- docs-sync: learned-through commit=deadbeef comment=2026-07-20T10:00:00Z -->"
   const body = renderBody({
     date: "2026-07-27",
     since: "2026-07-17T00:00:00.000Z",
     through,
+    learnedThrough: learnedMarker,
     changesRows,
     pendingRows,
     skippedRows,
@@ -1079,6 +1107,7 @@ function case4_routing() {
     note: "",
   })
   assert.ok(body.includes(`<!-- docs-sync: processed-through ${through} -->`))
+  assert.ok(body.includes(learnedMarker), "learned-through marker must appear in rendered body")
   const extChanges = extractSectionRows(body, "changes")
   const extPending = extractSectionRows(body, "pending")
   const extSkipped = extractSectionRows(body, "skipped")
@@ -1106,6 +1135,7 @@ function case4_routing() {
       date: "2026-07-27",
       since: "s",
       through: "t",
+      learnedThrough: "",
       changesRows: [],
       pendingRows: [],
       skippedRows: forgedRows.skippedRows,
@@ -1417,7 +1447,7 @@ function case9_reverts() {
   console.log("case 9: revert interception")
 
   // --- revertTitleKind ---
-  assert.equal(revertTitleKind('revert(cli): restore opt-in stream idle timeouts'), "conventional")
+  assert.equal(revertTitleKind("revert(cli): restore opt-in stream idle timeouts"), "conventional")
   assert.equal(revertTitleKind('Revert "feat(cli): default stream watchdog"'), "github-native")
   assert.equal(revertTitleKind("REVERT: all of it"), "conventional")
   assert.equal(revertTitleKind("feat(cli): add x"), null)
@@ -1824,6 +1854,1603 @@ Reverts #12249 and #12481.
   }
 }
 
+// ---------------------------------------------------------------------------
+// Case 10 — learnings extraction, validation, injection, upsert safety
+// ---------------------------------------------------------------------------
+function case10_learnings() {
+  console.log("case 10: learnings")
+
+  // --- helpers for extraction runs ---
+  function writeFixture(cwd, data) {
+    const f = path.join(cwd, "fixture.json")
+    fs.writeFileSync(f, JSON.stringify(data, null, 2))
+    return f
+  }
+
+  function writeExtractionDelta(cwd, delta) {
+    fs.mkdirSync(path.join(cwd, "docs-sync-out"), { recursive: true })
+    fs.writeFileSync(path.join(cwd, "docs-sync-out", "extraction-delta.json"), JSON.stringify(delta, null, 2))
+  }
+
+  // Prepare a git repo for learn.mjs tests: set origin refs, create docs-sync-out.
+  function setupLearnRepo(dir) {
+    fs.mkdirSync(path.join(dir, "docs-sync-out"), { recursive: true })
+    gitIn(dir, ["update-ref", "refs/remotes/origin/main", "main"])
+    gitIn(dir, ["update-ref", "refs/remotes/origin/docs/auto-sync", "docs/auto-sync"])
+    return dir
+  }
+
+  const githubBotEmail = "41898282+github-actions[bot]@users.noreply.github.com"
+  const kiloconnectBotEmail = "240665456+kiloconnect[bot]@users.noreply.github.com"
+
+  // 10a — three commit classes
+  {
+    console.log("  10a — three commit classes")
+    const dir = mktemp("docs-sync-learn-a-")
+    initRepoWithIdentity(dir)
+    fs.writeFileSync(path.join(dir, "base.txt"), "base\n")
+    gitIn(dir, ["add", "base.txt"])
+    gitIn(dir, ["commit", "-m", "base"])
+
+    // Branch
+    gitIn(dir, ["checkout", "-b", "docs/auto-sync"])
+    // 1. kiloconnect[bot] commit that touches packages/kilo-docs/pages/x.md
+    gitIn(dir, ["config", "user.email", kiloconnectBotEmail])
+    fs.mkdirSync(path.join(dir, "packages", "kilo-docs", "pages"), { recursive: true })
+    fs.writeFileSync(path.join(dir, "packages", "kilo-docs", "pages", "x.md"), "# x\n")
+    gitIn(dir, ["add", "packages/kilo-docs/pages/x.md"])
+    gitIn(dir, ["commit", "-m", "docs: add x page"])
+    const kiloconnectSha = gitIn(dir, ["rev-parse", "HEAD"])
+    // 2. github-actions[bot] commit
+    gitIn(dir, ["config", "user.email", githubBotEmail])
+    fs.writeFileSync(path.join(dir, "packages", "kilo-docs", "pages", "y.md"), "# y\n")
+    gitIn(dir, ["add", "packages/kilo-docs/pages/y.md"])
+    gitIn(dir, ["commit", "-m", "docs: add y page"])
+    // 3. Merge commit (non-merge filter)
+    gitIn(dir, ["config", "user.email", "someone@example.com"])
+    gitIn(dir, ["checkout", "-b", "tmp-merge"])
+    fs.writeFileSync(path.join(dir, "z.txt"), "z\n")
+    gitIn(dir, ["add", "z.txt"])
+    gitIn(dir, ["commit", "-m", "tmp"])
+    gitIn(dir, ["checkout", "docs/auto-sync"])
+    gitIn(dir, ["merge", "--no-ff", "tmp-merge", "-m", "merge tmp"])
+    // 4. commit reachable from main
+    gitIn(dir, ["checkout", "main"])
+    fs.writeFileSync(path.join(dir, "main-only.txt"), "main only\n")
+    gitIn(dir, ["add", "main-only.txt"])
+    gitIn(dir, ["commit", "-m", "main only"])
+
+    gitIn(dir, ["checkout", "docs/auto-sync"])
+    const tip = gitIn(dir, ["rev-parse", "HEAD"])
+
+    // Setup origin refs (needed by learn.mjs git commands)
+    const cwd = setupLearnRepo(dir)
+
+    const fixturePath = writeFixture(dir, {
+      pr: { number: 1, head: { ref: "docs/auto-sync" }, body: "", user: { login: "github-actions[bot]" } },
+      comments: [],
+    })
+
+    const callLog = path.join(dir, "kilo-calls.log")
+    const kiloDir = makeStubKiloDir({ mode: "extraction-delta", callLog })
+    writeExtractionDelta(dir, { add: [], remove: [] })
+
+    const result = runNodeScript(LEARN_SCRIPT, {
+      cwd: dir,
+      kiloDir,
+      env: {
+        TRIAGE_MODEL: "test/model",
+        DOCS_SYNC_FIXTURE: fixturePath,
+        LEARNINGS_BUDGET_MINUTES: "1",
+        DOCS_SYNC_BACKOFF_MS: "0",
+      },
+    })
+
+    // Assert: input file written, exactly one correction — kiloconnect only.
+    // github-actions[bot] commit excluded (criterion 5), merge commit excluded
+    // via --no-merges, main-reachable commit excluded by origin/main range (criterion 6).
+    const inputFile = path.join(dir, "docs-sync-out", "learnings-input.json")
+    assert.ok(fs.existsSync(inputFile), `expected ${inputFile}`)
+    const input = JSON.parse(fs.readFileSync(inputFile, "utf8"))
+    assert.equal(input.corrections.length, 1, "exactly one correction (kiloconnect commit)")
+    assert.equal(
+      input.corrections[0].source,
+      `commit:${kiloconnectSha.slice(0, 7)}`,
+      "correction must be kiloconnect commit only",
+    )
+  }
+
+  // 10rz — timestamp correlation with different timezone offsets
+  // A comment must map to the chronologically earliest eligible commit even when
+  // timestamps use different timezone offsets (Z vs +05:00).
+  {
+    console.log("  10rz — timestamp correlation")
+    const dir = mktemp("docs-sync-learn-rz-")
+    initRepoWithIdentity(dir)
+    fs.writeFileSync(path.join(dir, "base.txt"), "base\n")
+    gitIn(dir, ["add", "base.txt"])
+    gitIn(dir, ["commit", "-m", "base"])
+
+    gitIn(dir, ["checkout", "-b", "docs/auto-sync"])
+
+    // Commit A: non-UTC offset, chronologically earliest (UTC 08:00)
+    // iso = 2026-08-03T13:00:00+05:00
+    fs.mkdirSync(path.join(dir, "packages", "kilo-docs", "pages"), { recursive: true })
+    fs.writeFileSync(path.join(dir, "packages", "kilo-docs", "pages", "x.md"), "# x\n")
+    gitIn(dir, ["add", "packages/kilo-docs/pages/x.md"])
+    gitIn(dir, ["commit", "-m", "first edit x", "--author", `kiloconnect[bot] <${kiloconnectBotEmail}>`], {
+      GIT_COMMITTER_DATE: "2026-08-03T13:00:00+05:00",
+    })
+    const shaA = gitIn(dir, ["rev-parse", "HEAD"])
+
+    // Commit B: UTC offset, chronologically later (UTC 09:00)
+    // iso = 2026-08-03T09:00:00Z — string comparison would pick this as "earlier" (09 < 13)
+    // but chronologically A is earlier (08:00 < 09:00)
+    fs.writeFileSync(path.join(dir, "packages", "kilo-docs", "pages", "x.md"), "# x\n## edit\n")
+    gitIn(dir, ["add", "packages/kilo-docs/pages/x.md"])
+    gitIn(dir, ["commit", "-m", "second edit x", "--author", `kiloconnect[bot] <${kiloconnectBotEmail}>`], {
+      GIT_COMMITTER_DATE: "2026-08-03T09:00:00Z",
+    })
+    const shaB = gitIn(dir, ["rev-parse", "HEAD"])
+
+    // Seed LEARNINGS.md so existing entries are non-empty but irrelevant
+    const existing = [
+      { id: "pre", rule: "Pre-existing rule.", scope: "both", source: "commit:0000000", date: "2026-01-01" },
+    ]
+    const learningsPath = path.join(dir, "packages", "kilo-docs", "LEARNINGS.md")
+    fs.mkdirSync(path.dirname(learningsPath), { recursive: true })
+    fs.writeFileSync(learningsPath, renderLearnings(existing))
+    gitIn(dir, ["add", "packages/kilo-docs/LEARNINGS.md"])
+    gitIn(dir, ["commit", "-m", "seed learnings", "--author", `kiloconnect[bot] <${kiloconnectBotEmail}>`])
+
+    const cwd = setupLearnRepo(dir)
+
+    // Comment at UTC 05:30 on x.md — before both commits chronologically.
+    // 05:30 < 08:00 (A) and 05:30 < 09:00 (B) → both eligible
+    // The chronologically earliest eligible commit is A (08:00).
+    const fixturePath = writeFixture(cwd, {
+      pr: { number: 1, head: { ref: "docs/auto-sync" }, body: "", user: { login: "github-actions[bot]" } },
+      comments: [
+        {
+          id: 101,
+          created_at: "2026-08-03T05:30:00Z",
+          path: "packages/kilo-docs/pages/x.md",
+          body: "Please fix the docs.",
+          author_association: "MEMBER",
+          user: { login: "maintainer" },
+        },
+      ],
+    })
+
+    const kiloDir = makeStubKiloDir({ mode: "extraction-delta", callLog: path.join(cwd, "kilo-calls.log") })
+    writeExtractionDelta(cwd, { add: [], remove: [] })
+
+    const result = runNodeScript(LEARN_SCRIPT, {
+      cwd,
+      kiloDir,
+      env: {
+        TRIAGE_MODEL: "test/model",
+        DOCS_SYNC_FIXTURE: fixturePath,
+        LEARNINGS_BUDGET_MINUTES: "1",
+        DOCS_SYNC_BACKOFF_MS: "0",
+      },
+    })
+
+    // Read learnings-input.json to inspect the correlation result
+    const inputFile = path.join(cwd, "docs-sync-out", "learnings-input.json")
+    assert.ok(fs.existsSync(inputFile), "learnings-input.json must exist")
+    const input = JSON.parse(fs.readFileSync(inputFile, "utf8"))
+
+    // Both commits must appear as corrections
+    const commitA = input.corrections.find((c) => c.source === `commit:${shaA.slice(0, 7)}`)
+    const commitB = input.corrections.find((c) => c.source === `commit:${shaB.slice(0, 7)}`)
+    assert.ok(commitA, "commit A must be in corrections")
+    assert.ok(commitB, "commit B must be in corrections")
+
+    // Comment must be associated with commit A (chronologically earliest)
+    assert.ok(commitA.comment, "commit A must have the comment associated")
+    assert.equal(commitA.comment.path, "packages/kilo-docs/pages/x.md")
+    assert.equal(commitB.comment, undefined, "commit B must not have the comment associated")
+
+    // No standalone comment candidate — the comment was correlated, not orphaned
+    const standalone = input.corrections.filter((c) => c.source && c.source.startsWith("comment:"))
+    assert.equal(standalone.length, 0, "comment must be associated, not standalone")
+  }
+
+  // 10b — watermark suppression (no model call when marker covers all)
+  {
+    console.log("  10b — watermark suppression")
+    const dir = mktemp("docs-sync-learn-b-")
+    initRepoWithIdentity(dir)
+    fs.writeFileSync(path.join(dir, "base.txt"), "base\n")
+    gitIn(dir, ["add", "base.txt"])
+    gitIn(dir, ["commit", "-m", "base"])
+
+    gitIn(dir, ["checkout", "-b", "docs/auto-sync"])
+    // corrective commit
+    fs.mkdirSync(path.join(dir, "packages", "kilo-docs", "pages"), { recursive: true })
+    fs.writeFileSync(path.join(dir, "packages", "kilo-docs", "pages", "x.md"), "# x\n")
+    gitIn(dir, ["add", "packages/kilo-docs/pages/x.md"])
+    gitIn(dir, ["commit", "-m", "docs update", "--author", `kiloconnect[bot] <${kiloconnectBotEmail}>`])
+
+    // Write LEARNINGS.md on the branch first, so the marker can point to the tip after it
+    const existing = [
+      { id: "test", rule: "existing rule", scope: "both", source: "commit:0000000", date: "2026-01-01" },
+    ]
+    const learningsPath = path.join(dir, "packages", "kilo-docs", "LEARNINGS.md")
+    const learningsContent = renderLearnings(existing)
+    fs.mkdirSync(path.dirname(learningsPath), { recursive: true })
+    fs.writeFileSync(learningsPath, learningsContent)
+    gitIn(dir, ["add", "packages/kilo-docs/LEARNINGS.md"])
+    gitIn(dir, ["commit", "-m", "seed learnings"])
+
+    const tip = gitIn(dir, ["rev-parse", "HEAD"])
+    const tipDate = new Date().toISOString()
+
+    const cwd = setupLearnRepo(dir)
+    const body = `<!-- docs-sync: learned-through commit=${tip} comment=${tipDate} -->`
+    const fixturePath = writeFixture(cwd, {
+      pr: { number: 1, head: { ref: "docs/auto-sync" }, body, user: { login: "github-actions[bot]" } },
+      comments: [],
+    })
+
+    const callLog = path.join(cwd, "kilo-calls.log")
+    const kiloDir = makeStubKiloDir({ mode: "extraction-delta", callLog })
+    writeExtractionDelta(cwd, { add: [], remove: [] })
+
+    fs.writeFileSync(path.join(cwd, "docs-sync-out", "learnings.json"), JSON.stringify(existing, null, 2))
+
+    const result = runNodeScript(LEARN_SCRIPT, {
+      cwd,
+      kiloDir,
+      env: {
+        TRIAGE_MODEL: "test/model",
+        DOCS_SYNC_FIXTURE: fixturePath,
+        LEARNINGS_BUDGET_MINUTES: "1",
+        DOCS_SYNC_BACKOFF_MS: "0",
+      },
+    })
+
+    // Assert: stub never invoked, learnings.json unchanged, no model call
+    const calls = fs.existsSync(callLog) ? fs.readFileSync(callLog, "utf8").trim() : ""
+    assert.equal(calls, "", `kilo must not be invoked when marker covers all; got ${calls}`)
+    const out = JSON.parse(fs.readFileSync(path.join(cwd, "docs-sync-out", "learnings.json"), "utf8"))
+    assert.deepEqual(out, existing, "learnings.json must equal existing entries")
+
+    // Run apply and prove LEARNINGS.md is byte-unchanged
+    const lp = path.join(cwd, "packages", "kilo-docs", "LEARNINGS.md")
+    const before = fs.readFileSync(lp, "utf8")
+    runNodeScript(LEARN_SCRIPT, {
+      cwd,
+      kiloDir,
+      args: ["--apply"],
+      env: { DOCS_SYNC_BACKOFF_MS: "0" },
+    })
+    const after = fs.readFileSync(lp, "utf8")
+    assert.equal(after, before, "LEARNINGS.md must be byte-unchanged after apply")
+  }
+
+  // 10c — rerun idempotency
+  {
+    console.log("  10c — rerun idempotency")
+    const dir = mktemp("docs-sync-learn-c-")
+    initRepoWithIdentity(dir)
+    fs.writeFileSync(path.join(dir, "base.txt"), "base\n")
+    gitIn(dir, ["add", "base.txt"])
+    gitIn(dir, ["commit", "-m", "base"])
+
+    gitIn(dir, ["checkout", "-b", "docs/auto-sync"])
+    fs.mkdirSync(path.join(dir, "packages", "kilo-docs", "pages"), { recursive: true })
+    fs.writeFileSync(path.join(dir, "packages", "kilo-docs", "pages", "x.md"), "# x\n")
+    gitIn(dir, ["add", "packages/kilo-docs/pages/x.md"])
+    gitIn(dir, ["commit", "-m", "docs update", "--author", `kiloconnect[bot] <${kiloconnectBotEmail}>`])
+    let tip = gitIn(dir, ["rev-parse", "HEAD"])
+
+    const add = [
+      {
+        id: "new-rule",
+        rule: "A new rule from testing.",
+        scope: "both",
+        source: `commit:${tip.slice(0, 7)}`,
+        date: "2026-08-03",
+      },
+    ]
+    let firstLEARNINGS
+
+    // First run
+    {
+      const cwd = setupLearnRepo(dir)
+      const fixturePath = writeFixture(cwd, {
+        pr: { number: 1, head: { ref: "docs/auto-sync" }, body: "", user: { login: "github-actions[bot]" } },
+        comments: [],
+      })
+      const kiloDir = makeStubKiloDir({ mode: "extraction-delta", callLog: path.join(cwd, "kilo-calls.log") })
+      writeExtractionDelta(cwd, { add, remove: [] })
+      const result = runNodeScript(LEARN_SCRIPT, {
+        cwd,
+        kiloDir,
+        env: {
+          TRIAGE_MODEL: "test/model",
+          DOCS_SYNC_FIXTURE: fixturePath,
+          LEARNINGS_BUDGET_MINUTES: "1",
+          DOCS_SYNC_BACKOFF_MS: "0",
+        },
+      })
+      const out1 = JSON.parse(fs.readFileSync(path.join(cwd, "docs-sync-out", "learnings.json"), "utf8"))
+      assert.equal(out1.length, 1)
+      assert.equal(out1[0].id, "new-rule")
+      // Write LEARNINGS.md on the branch so second run sees existing entries
+      const learningsPath = path.join(dir, "packages", "kilo-docs", "LEARNINGS.md")
+      fs.mkdirSync(path.dirname(learningsPath), { recursive: true })
+      fs.writeFileSync(learningsPath, renderLearnings(out1))
+      gitIn(dir, ["add", "packages/kilo-docs/LEARNINGS.md"])
+      gitIn(dir, ["commit", "-m", "seed learnings"])
+      tip = gitIn(dir, ["rev-parse", "HEAD"])
+      firstLEARNINGS = fs.readFileSync(path.join(dir, "packages", "kilo-docs", "LEARNINGS.md"), "utf8")
+    }
+
+    // Second run with marker covering first run's result
+    {
+      const cwd = setupLearnRepo(dir)
+      const body = `<!-- docs-sync: learned-through commit=${tip} comment=2026-08-03T12:00:00Z -->`
+      const fixturePath = writeFixture(cwd, {
+        pr: { number: 1, head: { ref: "docs/auto-sync" }, body, user: { login: "github-actions[bot]" } },
+        comments: [],
+      })
+      const callLog2 = path.join(cwd, "kilo-calls-run2.log")
+      const kiloDir2 = makeStubKiloDir({ mode: "extraction-delta", callLog: callLog2 })
+      writeExtractionDelta(cwd, { add, remove: [] })
+      const result = runNodeScript(LEARN_SCRIPT, {
+        cwd,
+        kiloDir: kiloDir2,
+        env: {
+          TRIAGE_MODEL: "test/model",
+          DOCS_SYNC_FIXTURE: fixturePath,
+          LEARNINGS_BUDGET_MINUTES: "1",
+          DOCS_SYNC_BACKOFF_MS: "0",
+        },
+      })
+      const calls2 = fs.existsSync(callLog2) ? fs.readFileSync(callLog2, "utf8").trim() : ""
+      assert.equal(calls2, "", "second run must not invoke kilo")
+      const out2 = JSON.parse(fs.readFileSync(path.join(cwd, "docs-sync-out", "learnings.json"), "utf8"))
+      assert.equal(out2.length, 1)
+      assert.equal(out2[0].id, "new-rule")
+      // Run apply and prove LEARNINGS.md is byte-identical after idempotent rerun
+      runNodeScript(LEARN_SCRIPT, {
+        cwd,
+        kiloDir: kiloDir2,
+        args: ["--apply"],
+        env: { DOCS_SYNC_BACKOFF_MS: "0" },
+      })
+      const afterApply = fs.readFileSync(path.join(dir, "packages", "kilo-docs", "LEARNINGS.md"), "utf8")
+      assert.equal(afterApply.length, firstLEARNINGS.length, "LEARNINGS.md must be same length after apply")
+      assert.equal(afterApply, firstLEARNINGS, "LEARNINGS.md must be byte-identical after apply")
+    }
+  }
+
+  // 10d — contradiction replacement (applyDelta)
+  {
+    console.log("  10d — contradiction replacement")
+    const old = [
+      { id: "old-rule", rule: "Old rule text.", scope: "both", source: "commit:aaaaaaa", date: "2026-01-01" },
+    ]
+    const add = [
+      { id: "new-rule", rule: "New rule text.", scope: "both", source: "commit:bbbbbbb", date: "2026-02-01" },
+    ]
+    const delta = { add, remove: ["old-rule"] }
+    const result = applyDelta(old, delta)
+    assert.equal(result.length, 1)
+    assert.equal(result[0].id, "new-rule")
+    // Third delta touching neither does not bring old back
+    const again = applyDelta(result, { add: [], remove: [] })
+    assert.equal(again.length, 1)
+    assert.equal(again[0].id, "new-rule")
+  }
+
+  // 10e — prompt injection (triage/edit argv carry tagged rules)
+  {
+    console.log("  10e — prompt injection")
+    const dir = mktemp("docs-sync-learn-e-")
+    initRepoWithIdentity(dir)
+    fs.writeFileSync(path.join(dir, "base.txt"), "base\n")
+    gitIn(dir, ["add", "base.txt"])
+    gitIn(dir, ["commit", "-m", "base"])
+    gitIn(dir, ["checkout", "-b", "docs/auto-sync"])
+    // Add a corrective commit so extraction has a candidate
+    fs.mkdirSync(path.join(dir, "packages", "kilo-docs", "pages"), { recursive: true })
+    fs.writeFileSync(path.join(dir, "packages", "kilo-docs", "pages", "x.md"), "# x\n")
+    gitIn(dir, ["add", "packages/kilo-docs/pages/x.md"])
+    gitIn(dir, ["commit", "-m", "docs update", "--author", `kiloconnect[bot] <${kiloconnectBotEmail}>`])
+    const commitSha = gitIn(dir, ["rev-parse", "HEAD"])
+
+    const cwd = setupLearnRepo(dir)
+    const fixturePath = writeFixture(cwd, {
+      pr: { number: 1, head: { ref: "docs/auto-sync" }, body: "", user: { login: "github-actions[bot]" } },
+      comments: [],
+    })
+    const callLog = path.join(cwd, "kilo-calls.log")
+    const kiloDir = makeStubKiloDir({ mode: "extraction-delta", callLog })
+    // Three entries: triage, edit, both — all from the same candidate source
+    const src = `commit:${commitSha.slice(0, 7)}`
+    writeExtractionDelta(cwd, {
+      add: [
+        { id: "triage-rule", rule: "Triage-only rule text.", scope: "triage", source: src, date: "2026-08-01" },
+        { id: "edit-rule", rule: "Edit-only rule text.", scope: "edit", source: src, date: "2026-08-02" },
+        { id: "both-rule", rule: "Both scope rule text.", scope: "both", source: src, date: "2026-08-03" },
+      ],
+      remove: [],
+    })
+
+    // Run extraction so it writes learnings-<scope>.md blocks (extraction step 13).
+    // Only extraction writes these files; --apply writes only LEARNINGS.md.
+    runNodeScript(LEARN_SCRIPT, {
+      cwd,
+      kiloDir,
+      env: {
+        TRIAGE_MODEL: "test/model",
+        DOCS_SYNC_FIXTURE: fixturePath,
+        LEARNINGS_BUDGET_MINUTES: "1",
+        DOCS_SYNC_BACKOFF_MS: "0",
+      },
+    })
+
+    const triageBlockPath = path.join(cwd, "docs-sync-out", "learnings-triage.md")
+    const editBlockPath = path.join(cwd, "docs-sync-out", "learnings-edit.md")
+    assert.ok(fs.existsSync(triageBlockPath), "learnings-triage.md must exist")
+    assert.ok(fs.existsSync(editBlockPath), "learnings-edit.md must exist")
+
+    // Run triage.mjs against a recording stub. Copy the learnings block into
+    // its cwd so readLearningsBlock picks it up.
+    {
+      const triageCwd = setupTriageCwd([samplePr(1)])
+      fs.copyFileSync(triageBlockPath, path.join(triageCwd, "docs-sync-out", "learnings-triage.md"))
+      const triageCallLog = path.join(triageCwd, "triage-calls.log")
+      const triageKiloDir = makeStubKiloDir({ mode: "record", callLog: triageCallLog })
+      runNodeScript(TRIAGE_SCRIPT, {
+        cwd: triageCwd,
+        kiloDir: triageKiloDir,
+        env: { TRIAGE_MODEL: "test/model", DOCS_SYNC_BACKOFF_MS: "0" },
+      })
+      const logText = fs.readFileSync(triageCallLog, "utf8")
+      assert.ok(logText.includes("Triage-only rule text"), "triage argv must contain triage rule")
+      assert.ok(logText.includes("Both scope rule text"), "triage argv must contain both rule")
+      assert.ok(!logText.includes("Edit-only rule text"), "triage argv must not contain edit-only rule")
+    }
+
+    // Run edit.mjs against a recording stub.
+    {
+      const triageEntry = {
+        pr: 1,
+        url: "https://github.com/Kilo-Org/cloud/pull/1",
+        docs_worthy: true,
+        reason: "needs docs",
+        target_sections: [],
+        priority: "medium",
+      }
+      const editCwd = setupEditCwd([samplePr(1)], [triageEntry])
+      fs.copyFileSync(editBlockPath, path.join(editCwd, "docs-sync-out", "learnings-edit.md"))
+      const editCallLog = path.join(editCwd, "edit-calls.log")
+      const editKiloDir = makeStubKiloDir({ mode: "record", callLog: editCallLog })
+      runNodeScript(EDIT_SCRIPT, {
+        cwd: editCwd,
+        kiloDir: editKiloDir,
+        env: { EDIT_MODEL: "test/model", DOCS_SYNC_BACKOFF_MS: "0" },
+      })
+      const logText = fs.readFileSync(editCallLog, "utf8")
+      assert.ok(logText.includes("Edit-only rule text"), "edit argv must contain edit rule")
+      assert.ok(logText.includes("Both scope rule text"), "edit argv must contain both rule")
+      assert.ok(!logText.includes("Triage-only rule text"), "edit argv must not contain triage-only rule")
+    }
+  }
+
+  // 10f — failure path
+  {
+    console.log("  10f — failure path")
+    const dir = mktemp("docs-sync-learn-f-")
+    initRepoWithIdentity(dir)
+    fs.writeFileSync(path.join(dir, "base.txt"), "base\n")
+    gitIn(dir, ["add", "base.txt"])
+    gitIn(dir, ["commit", "-m", "base"])
+    gitIn(dir, ["checkout", "-b", "docs/auto-sync"])
+    fs.mkdirSync(path.join(dir, "packages", "kilo-docs", "pages"), { recursive: true })
+    fs.writeFileSync(path.join(dir, "packages", "kilo-docs", "pages", "x.md"), "# x\n")
+    gitIn(dir, ["add", "packages/kilo-docs/pages/x.md"])
+    gitIn(dir, ["commit", "-m", "docs update", "--author", `kiloconnect[bot] <${kiloconnectBotEmail}>`])
+
+    const existing = [
+      { id: "test", rule: "existing rule", scope: "both", source: "commit:0000000", date: "2026-01-01" },
+    ]
+    // Write LEARNINGS.md on the branch so learn.mjs reads it as existing entries
+    const learningsPath = path.join(dir, "packages", "kilo-docs", "LEARNINGS.md")
+    fs.mkdirSync(path.dirname(learningsPath), { recursive: true })
+    fs.writeFileSync(learningsPath, renderLearnings(existing))
+    gitIn(dir, ["add", "packages/kilo-docs/LEARNINGS.md"])
+    gitIn(dir, ["commit", "-m", "seed learnings"])
+
+    const cwd = setupLearnRepo(dir)
+    const fixturePath = writeFixture(cwd, {
+      pr: { number: 1, head: { ref: "docs/auto-sync" }, body: "", user: { login: "github-actions[bot]" } },
+      comments: [],
+    })
+
+    // Stub exits 0 with garbage stdout (stderr-exit0 mode)
+    const stderrText = "some fake error stream"
+    const kiloDir = makeStubKiloDir({ mode: "stderr-exit0", stderrText })
+
+    const outputFile = path.join(cwd, "gh-output-f")
+    const result = runNodeScript(LEARN_SCRIPT, {
+      cwd,
+      kiloDir,
+      env: {
+        TRIAGE_MODEL: "test/model",
+        DOCS_SYNC_FIXTURE: fixturePath,
+        LEARNINGS_BUDGET_MINUTES: "1",
+        DOCS_SYNC_BACKOFF_MS: "0",
+        GITHUB_OUTPUT: outputFile,
+      },
+    })
+
+    assert.equal(result.status, 0, "learn.mjs must exit 0 on failure")
+    const out = JSON.parse(fs.readFileSync(path.join(cwd, "docs-sync-out", "learnings.json"), "utf8"))
+    assert.deepEqual(out, existing, "learnings.json must equal existing entries on failure")
+    // No marker PATCH file
+    assert.ok(!fs.existsSync(`${fixturePath}.patched`), "no marker PATCH on failure")
+    // No learned_through output
+    if (fs.existsSync(outputFile)) {
+      const ghOut = fs.readFileSync(outputFile, "utf8")
+      assert.ok(!ghOut.includes("learned_through="), "GITHUB_OUTPUT must not contain learned_through on failure")
+    }
+
+    // Run apply and prove LEARNINGS.md is byte-unchanged
+    const lp = path.join(cwd, "packages", "kilo-docs", "LEARNINGS.md")
+    const before = fs.readFileSync(lp, "utf8")
+    runNodeScript(LEARN_SCRIPT, {
+      cwd,
+      kiloDir,
+      args: ["--apply"],
+      env: { DOCS_SYNC_BACKOFF_MS: "0" },
+    })
+    const after = fs.readFileSync(lp, "utf8")
+    assert.equal(after, before, "LEARNINGS.md must be byte-unchanged after apply on failure")
+  }
+
+  // 10g — general-rule check (validateDelta rejections)
+  {
+    console.log("  10g — general-rule check")
+    const existing = []
+    const sources = ["commit:aaaaaaa"]
+    const entryWithPR = {
+      id: "bad-pr",
+      rule: "See #12716 for details",
+      scope: "both",
+      source: "commit:aaaaaaa",
+      date: "2026-08-03",
+    }
+    const entryWithURL = {
+      id: "bad-url",
+      rule: "Check https://example.com",
+      scope: "both",
+      source: "commit:aaaaaaa",
+      date: "2026-08-03",
+    }
+    const entryWithPerson = {
+      id: "bad-person",
+      rule: "Ask @emilieschario",
+      scope: "both",
+      source: "commit:aaaaaaa",
+      date: "2026-08-03",
+    }
+    const entryWithPage = {
+      id: "bad-page",
+      rule: "Edit packages/kilo-docs/pages/x.md",
+      scope: "both",
+      source: "commit:aaaaaaa",
+      date: "2026-08-03",
+    }
+    const entryBadSource = {
+      id: "bad-source",
+      rule: "A valid sentence.",
+      scope: "both",
+      source: "invented",
+      date: "2026-08-03",
+    }
+    const entryBadScope = {
+      id: "bad-scope",
+      rule: "A valid sentence.",
+      scope: "wrong",
+      source: "commit:aaaaaaa",
+      date: "2026-08-03",
+    }
+    const entryCollide = {
+      id: "existing-id",
+      rule: "A valid sentence.",
+      scope: "both",
+      source: "commit:aaaaaaa",
+      date: "2026-08-03",
+    }
+    const entryBadDate = {
+      id: "bad-date",
+      rule: "A valid sentence.",
+      scope: "both",
+      source: "commit:aaaaaaa",
+      date: "not-a-date",
+    }
+    const entryRemoveUnknown = {
+      id: "valid",
+      rule: "A valid sentence.",
+      scope: "both",
+      source: "commit:aaaaaaa",
+      date: "2026-08-03",
+    }
+
+    const existingWithId = [
+      { id: "existing-id", rule: "Existing rule.", scope: "both", source: "commit:aaaaaaa", date: "2026-01-01" },
+    ]
+
+    // PR number
+    {
+      const { rejected } = validateDelta(
+        { add: [entryWithPR], remove: [] },
+        { existing, candidateSources: sources, deletedInWindow: [] },
+      )
+      assert.equal(rejected.length, 1, "PR number must be rejected")
+      assert.ok(rejected[0].reason, "rejection must carry a reason")
+    }
+
+    // URL — docs-check-links.yml link-checks LEARNINGS.md with fail:true, so
+    // a URL in a rule would break CI on every bot commit.
+    {
+      const { rejected } = validateDelta(
+        { add: [entryWithURL], remove: [] },
+        { existing, candidateSources: sources, deletedInWindow: [] },
+      )
+      assert.equal(rejected.length, 1, "URL must be rejected")
+    }
+
+    // Person
+    {
+      const { rejected } = validateDelta(
+        { add: [entryWithPerson], remove: [] },
+        { existing, candidateSources: sources, deletedInWindow: [] },
+      )
+      assert.equal(rejected.length, 1, "person reference must be rejected")
+    }
+
+    // Docs page
+    {
+      const { rejected } = validateDelta(
+        { add: [entryWithPage], remove: [] },
+        { existing, candidateSources: sources, deletedInWindow: [] },
+      )
+      assert.equal(rejected.length, 1, "docs page reference must be rejected")
+    }
+
+    // Bad source
+    {
+      const { rejected } = validateDelta(
+        { add: [entryBadSource], remove: [] },
+        { existing, candidateSources: sources, deletedInWindow: [] },
+      )
+      assert.equal(rejected.length, 1, "invented source must be rejected")
+    }
+
+    // Bad scope
+    {
+      const { rejected } = validateDelta(
+        { add: [entryBadScope], remove: [] },
+        { existing, candidateSources: sources, deletedInWindow: [] },
+      )
+      assert.equal(rejected.length, 1, "bad scope must be rejected")
+    }
+
+    // Colliding id
+    {
+      const { rejected } = validateDelta(
+        { add: [entryCollide], remove: [] },
+        { existing: existingWithId, candidateSources: sources, deletedInWindow: [] },
+      )
+      assert.equal(rejected.length, 1, "colliding id must be rejected")
+    }
+
+    // Remove unknown id
+    {
+      const { rejected } = validateDelta(
+        { add: [entryRemoveUnknown], remove: ["unknown-id"] },
+        { existing, candidateSources: sources, deletedInWindow: [] },
+      )
+      assert.equal(rejected.length, 1, "remove of unknown id must be rejected")
+    }
+
+    // Bad date
+    {
+      const { rejected } = validateDelta(
+        { add: [entryBadDate], remove: [] },
+        { existing, candidateSources: sources, deletedInWindow: [] },
+      )
+      assert.equal(rejected.length, 1, "bad date must be rejected")
+    }
+  }
+
+  // 10h — comment trust (isTrustedComment)
+  {
+    console.log("  10h — comment trust")
+    assert.equal(isTrustedComment({ author_association: "OWNER", user: { login: "owner-user" } }), true)
+    assert.equal(isTrustedComment({ author_association: "MEMBER", user: { login: "emilieschario" } }), true)
+    assert.equal(isTrustedComment({ author_association: "COLLABORATOR", user: { login: "collab-user" } }), true)
+    assert.equal(isTrustedComment({ author_association: "CONTRIBUTOR", user: { login: "kilo-code-bot[bot]" } }), false)
+    assert.equal(isTrustedComment({ author_association: "NONE", user: { login: "rando" } }), false)
+    // MEMBER whose login ends in [bot]
+    assert.equal(isTrustedComment({ author_association: "MEMBER", user: { login: "some-bot[bot]" } }), false)
+  }
+
+  // 10i — draft gate (nonContentFiles)
+  {
+    console.log("  10i — draft gate")
+    const files = ["packages/kilo-docs/LEARNINGS.md", "packages/kilo-docs/pages/a.md"]
+    const result = nonContentFiles(files)
+    assert.equal(result.length, 0, "LEARNINGS.md and pages must not trigger the draft gate")
+    // Still flags non-content
+    const withConfig = ["packages/kilo-docs/next.config.js"]
+    const flagged = nonContentFiles(withConfig)
+    assert.equal(flagged.length, 1, "next.config.js must still trigger the gate")
+    assert.equal(flagged[0], "packages/kilo-docs/next.config.js")
+  }
+
+  // 10j — no --auto on extraction call
+  {
+    console.log("  10j — no --auto on extraction call")
+    const src = fs.readFileSync(LEARN_SCRIPT, "utf8")
+
+    // Find the extraction-mode runKilo args array
+    const argsStart = src.indexOf("runKilo({")
+    assert.ok(argsStart >= 0, "runKilo call must exist in learn.mjs")
+    const argsBlock = src.slice(argsStart, src.indexOf("})", argsStart) + 2)
+    assert.ok(!argsBlock.includes("--auto"), "extraction runKilo must not include --auto")
+    assert.ok(argsBlock.includes("-f"), "extraction runKilo must include -f")
+  }
+
+  // 10k — hand-mangled file (parseLearnings)
+  {
+    console.log("  10k — hand-mangled file")
+    const text = `# header
+<!-- docs-sync:learnings:start -->
+- Valid rule. <!-- id=valid-rule scope=both source=commit:aaaaaaa date=2026-08-03 -->
+- Broken meta. <!-- id=broken-rule scope=not-a-scope source=bad date=bad -->
+Just prose, not a rule line.
+<!-- docs-sync:learnings:end -->`
+    const entries = parseLearnings(text)
+    assert.equal(entries.length, 1, "only valid entry must parse")
+    assert.equal(entries[0].id, "valid-rule")
+  }
+
+  // 10l — first-run fallback (main when branch has none)
+  // Prove the git commands learn.mjs relies on: when the branch file is absent,
+  // git show origin/<branch>:packages/kilo-docs/LEARNINGS.md fails, and
+  // git show origin/main:packages/kilo-docs/LEARNINGS.md returns the main's entries.
+  {
+    console.log("  10l — empty file fallback")
+    const dir = mktemp("docs-sync-learn-l-")
+    initRepoWithIdentity(dir)
+
+    // Write LEARNINGS.md on main
+    const entries = [
+      { id: "test", rule: "Test rule text.", scope: "both", source: "commit:aaaaaaa", date: "2026-01-01" },
+    ]
+    const lp = path.join(dir, "packages", "kilo-docs", "LEARNINGS.md")
+    fs.mkdirSync(path.dirname(lp), { recursive: true })
+    fs.writeFileSync(lp, renderLearnings(entries))
+    gitIn(dir, ["add", "packages/kilo-docs/LEARNINGS.md"])
+    gitIn(dir, ["commit", "-m", "main learnings"])
+
+    // Branch from main, then remove LEARNINGS.md
+    gitIn(dir, ["checkout", "-b", "docs/auto-sync"])
+    fs.rmSync(lp)
+    gitIn(dir, ["add", "packages/kilo-docs/LEARNINGS.md"])
+    gitIn(dir, ["commit", "-m", "remove learnings on branch"])
+
+    // Set up origin refs so git show origin/<ref> resolves
+    setupLearnRepo(dir)
+
+    // git show on branch must fail — file absent at that ref
+    let branchFailed = false
+    try {
+      gitIn(dir, ["show", "origin/docs/auto-sync:packages/kilo-docs/LEARNINGS.md"])
+    } catch {
+      branchFailed = true
+    }
+    assert.ok(branchFailed, "git show on branch must fail when LEARNINGS.md absent")
+
+    // git show on main must succeed with the main's entries
+    const mainContent = gitIn(dir, ["show", "origin/main:packages/kilo-docs/LEARNINGS.md"])
+    const parsed = parseLearnings(mainContent)
+    assert.equal(parsed.length, 1, "main fallback must return the main's entries")
+    assert.equal(parsed[0].id, "test")
+
+    // Also verify: empty parse and render (unit coverage of the empty case)
+    const empty = parseLearnings("")
+    assert.equal(empty.length, 0)
+    assert.deepEqual(empty, [])
+    const rendered = renderLearnings([])
+    assert.ok(rendered.includes("<!-- docs-sync:learnings:start -->"))
+    assert.ok(rendered.includes("<!-- docs-sync:learnings:end -->"))
+  }
+
+  // 10m — empty delta advances marker with no file change
+  {
+    console.log("  10m — empty delta marker advance")
+    const dir = mktemp("docs-sync-learn-m-")
+    initRepoWithIdentity(dir)
+    fs.writeFileSync(path.join(dir, "base.txt"), "base\n")
+    gitIn(dir, ["add", "base.txt"])
+    gitIn(dir, ["commit", "-m", "base"])
+    gitIn(dir, ["checkout", "-b", "docs/auto-sync"])
+    fs.mkdirSync(path.join(dir, "packages", "kilo-docs", "pages"), { recursive: true })
+    fs.writeFileSync(path.join(dir, "packages", "kilo-docs", "pages", "x.md"), "# x\n")
+    gitIn(dir, ["add", "packages/kilo-docs/pages/x.md"])
+    gitIn(dir, ["commit", "-m", "docs update", "--author", `kiloconnect[bot] <${kiloconnectBotEmail}>`])
+    const tip = gitIn(dir, ["rev-parse", "HEAD"])
+
+    const cwd = setupLearnRepo(dir)
+    const fixturePath = writeFixture(cwd, {
+      pr: { number: 1, head: { ref: "docs/auto-sync" }, body: "", user: { login: "github-actions[bot]" } },
+      comments: [],
+    })
+
+    const kiloDir = makeStubKiloDir({ mode: "extraction-delta", callLog: path.join(cwd, "kilo-calls.log") })
+    writeExtractionDelta(cwd, { add: [], remove: [] })
+
+    const existing = []
+    fs.writeFileSync(path.join(cwd, "docs-sync-out", "learnings.json"), JSON.stringify(existing, null, 2))
+    const learningsPath = path.join(cwd, "packages", "kilo-docs", "LEARNINGS.md")
+    fs.mkdirSync(path.dirname(learningsPath), { recursive: true })
+    fs.writeFileSync(learningsPath, renderLearnings(existing))
+    const before = fs.readFileSync(learningsPath, "utf8")
+
+    const outputFile = path.join(cwd, "gh-output-m")
+    const result = runNodeScript(LEARN_SCRIPT, {
+      cwd,
+      kiloDir,
+      env: {
+        TRIAGE_MODEL: "test/model",
+        DOCS_SYNC_FIXTURE: fixturePath,
+        LEARNINGS_BUDGET_MINUTES: "1",
+        DOCS_SYNC_BACKOFF_MS: "0",
+        GITHUB_OUTPUT: outputFile,
+      },
+    })
+
+    // learnings.json unchanged
+    const out = JSON.parse(fs.readFileSync(path.join(cwd, "docs-sync-out", "learnings.json"), "utf8"))
+    assert.deepEqual(out, existing)
+
+    // No learned_through output (empty delta route omits it per G5 table)
+    if (fs.existsSync(outputFile)) {
+      const ghOut = fs.readFileSync(outputFile, "utf8")
+      assert.ok(!ghOut.includes("learned_through="), "GITHUB_OUTPUT must not contain learned_through on empty delta")
+    }
+    const patched = `${fixturePath}.patched`
+    assert.ok(fs.existsSync(patched), "marker PATCH file must be written for empty delta")
+    const markerText = fs.readFileSync(patched, "utf8")
+    assert.ok(markerText.includes(tip), "marker PATCH must contain tip SHA")
+
+    runNodeScript(LEARN_SCRIPT, {
+      cwd,
+      kiloDir,
+      args: ["--apply"],
+      env: { DOCS_SYNC_BACKOFF_MS: "0" },
+    })
+    assert.equal(fs.readFileSync(learningsPath, "utf8"), before, "LEARNINGS.md must be byte-unchanged after apply")
+
+    // patchMarkerIntoBody: existing marker → replaced in place
+    {
+      const oldBody = "some text\n<!-- docs-sync: learned-through commit=old comment=old -->\nmore text\n"
+      const newLine = "<!-- docs-sync: learned-through commit=abc comment=2026-01-01 -->"
+      const patched = patchMarkerIntoBody(oldBody, newLine)
+      assert.ok(patched.includes(newLine), "new marker must be in body")
+      assert.ok(!patched.includes("commit=old"), "old marker must be gone")
+      assert.equal(
+        (patched.match(/<!--\s*docs-sync:\s*learned-through/g) || []).length,
+        1,
+        "exactly one marker after replace",
+      )
+    }
+
+    // patchMarkerIntoBody: no marker → appended
+    {
+      const oldBody = "no marker here\n"
+      const newLine = "<!-- docs-sync: learned-through commit=abc comment=2026-01-01 -->"
+      const patched = patchMarkerIntoBody(oldBody, newLine)
+      assert.ok(patched.includes(newLine))
+    }
+  }
+
+  // 10n — non-empty delta routes through upsert (not learn.mjs PATCH)
+  {
+    console.log("  10n — non-empty delta marker route")
+    const dir = mktemp("docs-sync-learn-n-")
+    initRepoWithIdentity(dir)
+    fs.writeFileSync(path.join(dir, "base.txt"), "base\n")
+    gitIn(dir, ["add", "base.txt"])
+    gitIn(dir, ["commit", "-m", "base"])
+    gitIn(dir, ["checkout", "-b", "docs/auto-sync"])
+    fs.mkdirSync(path.join(dir, "packages", "kilo-docs", "pages"), { recursive: true })
+    fs.writeFileSync(path.join(dir, "packages", "kilo-docs", "pages", "x.md"), "# x\n")
+    gitIn(dir, ["add", "packages/kilo-docs/pages/x.md"])
+    gitIn(dir, ["commit", "-m", "docs update", "--author", `kiloconnect[bot] <${kiloconnectBotEmail}>`])
+    const source = `commit:${gitIn(dir, ["rev-parse", "HEAD"]).slice(0, 7)}`
+    const tip = gitIn(dir, ["rev-parse", "HEAD"])
+
+    const cwd = setupLearnRepo(dir)
+    const fixturePath = writeFixture(cwd, {
+      pr: { number: 1, head: { ref: "docs/auto-sync" }, body: "", user: { login: "github-actions[bot]" } },
+      comments: [],
+    })
+
+    const kiloDir = makeStubKiloDir({ mode: "extraction-delta", callLog: path.join(cwd, "kilo-calls.log") })
+    writeExtractionDelta(cwd, {
+      add: [
+        { id: "new-rule", rule: "A new rule.", scope: "both", source: `commit:${tip.slice(0, 7)}`, date: "2026-08-03" },
+      ],
+      remove: [],
+    })
+
+    const summaryFile = path.join(cwd, "step-summary.md")
+    fs.writeFileSync(summaryFile, "")
+    const outputFile = path.join(cwd, "gh-output")
+    const result = runNodeScript(LEARN_SCRIPT, {
+      cwd,
+      kiloDir,
+      env: {
+        TRIAGE_MODEL: "test/model",
+        DOCS_SYNC_FIXTURE: fixturePath,
+        LEARNINGS_BUDGET_MINUTES: "1",
+        DOCS_SYNC_BACKOFF_MS: "0",
+        GITHUB_STEP_SUMMARY: summaryFile,
+        GITHUB_OUTPUT: outputFile,
+      },
+    })
+
+    // No marker PATCH file
+    assert.ok(!fs.existsSync(`${fixturePath}.patched`), "non-empty delta must not PATCH marker")
+
+    // Assert learned_through was written to GITHUB_OUTPUT (non-empty delta route)
+    const ghOut = fs.readFileSync(outputFile, "utf8")
+    assert.ok(ghOut.includes("learned_through="), "GITHUB_OUTPUT must contain learned_through on non-empty delta")
+    assert.ok(ghOut.includes(`commit=${tip}`), "learned_through must contain tip SHA")
+
+    // renderBody with learnedThrough marker
+    const marker = "<!-- docs-sync: learned-through commit=abc comment=2026-01-01 -->"
+    const body1 = renderBody({
+      date: "2026-08-03",
+      since: "2026-07-01T00:00:00.000Z",
+      through: "2026-08-03T00:00:00.000Z",
+      learnedThrough: marker,
+      changesRows: [],
+      pendingRows: [],
+      skippedRows: [],
+      verified: true,
+      draftReasons: [],
+      note: "",
+    })
+    assert.ok(body1.includes(marker), "renderBody must emit marker when given")
+
+    // renderBody with parameter omitted → no marker
+    const body2 = renderBody({
+      date: "2026-08-03",
+      since: "2026-07-01T00:00:00.000Z",
+      through: "2026-08-03T00:00:00.000Z",
+      changesRows: [],
+      pendingRows: [],
+      skippedRows: [],
+      verified: true,
+      draftReasons: [],
+      note: "",
+    })
+    assert.ok(!body2.includes("learned-through"), "renderBody without learnedThrough must emit no marker")
+    // Still round-trips
+    const extChanges = extractSectionRows(body2, "changes")
+    assert.deepEqual(extChanges, [])
+  }
+
+  // 10o — deleted-in-window rejection
+  {
+    console.log("  10o — deleted-in-window rejection")
+    // Normalized match catches near-identical wording
+    {
+      const delta = {
+        add: [
+          {
+            id: "dup",
+            rule: "do not document experimental features!",
+            scope: "both",
+            source: "commit:aaaaaaa",
+            date: "2026-08-03",
+          },
+        ],
+        remove: [],
+      }
+      const { rejected } = validateDelta(delta, {
+        existing: [],
+        candidateSources: ["commit:aaaaaaa"],
+        deletedInWindow: ["Do not document experimental features."],
+      })
+      assert.equal(rejected.length, 1, "normalized match must reject deleted rule")
+    }
+
+    // Different meaning on same topic — NOT rejected (accepted limit)
+    {
+      const delta = {
+        add: [
+          {
+            id: "good",
+            rule: "Document experimental features in a separate section.",
+            scope: "both",
+            source: "commit:aaaaaaa",
+            date: "2026-08-03",
+          },
+        ],
+        remove: [],
+      }
+      const { rejected } = validateDelta(delta, {
+        existing: [],
+        candidateSources: ["commit:aaaaaaa"],
+        deletedInWindow: ["Do not document experimental features."],
+      })
+      assert.equal(rejected.length, 0, "different rule on same topic must not be rejected")
+    }
+  }
+
+  // 10p — resolveLearnedThrough pure function and anti-drift assertions
+  {
+    console.log("  10p — resolveLearnedThrough + anti-drift")
+    // Unit tests on the pure export
+    // env value set wins over body marker
+    assert.equal(
+      resolveLearnedThrough({
+        envValue: "<!-- docs-sync: learned-through commit=env commit=env -->",
+        prBody: "<!-- docs-sync: learned-through commit=body comment=body -->",
+      }),
+      "<!-- docs-sync: learned-through commit=env commit=env -->",
+    )
+    // env unset, body marker present → body wins
+    assert.equal(
+      resolveLearnedThrough({ envValue: "", prBody: "<!-- docs-sync: learned-through commit=body comment=body -->" }),
+      "<!-- docs-sync: learned-through commit=body comment=body -->",
+    )
+    // both absent → empty string
+    assert.equal(resolveLearnedThrough({ envValue: "", prBody: "" }), "")
+    // env set to whitespace → treated as unset
+    assert.equal(
+      resolveLearnedThrough({
+        envValue: "   ",
+        prBody: "<!-- docs-sync: learned-through commit=body comment=body -->",
+      }),
+      "<!-- docs-sync: learned-through commit=body comment=body -->",
+    )
+
+    // renderBody emits no marker for ""
+    const bodyEmpty = renderBody({
+      date: "d",
+      since: "s",
+      through: "t",
+      learnedThrough: "",
+      changesRows: [],
+      pendingRows: [],
+      skippedRows: [],
+      verified: true,
+      draftReasons: [],
+      note: "",
+    })
+    assert.ok(!bodyEmpty.includes("learned-through"), "empty learnedThrough must emit no marker")
+
+    // Anti-drift: static-source assertions on upsert-pr.mjs
+    const upsertSrc = fs.readFileSync(path.join(HERE, "upsert-pr.mjs"), "utf8")
+
+    // (a) exactly one resolveLearnedThrough( call passing process.env.LEARNED_THROUGH
+    const calls = upsertSrc.match(/resolveLearnedThrough\(/g) || []
+    // One in the export definition, one in the call site
+    assert.ok(calls.length >= 2, `expected at least 2 resolveLearnedThrough( occurrences; got ${calls.length}`)
+    assert.ok(
+      upsertSrc.includes("process.env.LEARNED_THROUGH"),
+      "resolveLearnedThrough must receive process.env.LEARNED_THROUGH",
+    )
+    assert.ok(upsertSrc.includes("prBody"), "resolveLearnedThrough must receive prBody")
+
+    // (b) prBody is at function scope (let prBody before the if block)
+    const prBodyIdx = upsertSrc.indexOf('let prBody = ""')
+    assert.ok(prBodyIdx >= 0, 'prBody must be declared at function scope with let prBody = ""')
+    const ifIdx = upsertSrc.indexOf('if (mode === "update"')
+    assert.ok(prBodyIdx < ifIdx, 'let prBody must appear before if (mode === "update"...)')
+
+    // (c) renderBody({ argument object contains learnedThrough
+    const renderBodyIdx = upsertSrc.indexOf("const body = renderBody({")
+    assert.ok(renderBodyIdx >= 0, "renderBody call must exist")
+    const afterRenderBody = upsertSrc.slice(renderBodyIdx)
+    const renderBodyArgsEnd = afterRenderBody.indexOf("})")
+    const renderBodyArgs = afterRenderBody.slice(0, renderBodyArgsEnd)
+    assert.ok(renderBodyArgs.includes("learnedThrough"), "renderBody call in main() must pass learnedThrough")
+  }
+
+  // 10q — dry run makes no live write
+  {
+    console.log("  10q — dry run no live write")
+    const dir = mktemp("docs-sync-learn-q-")
+    initRepoWithIdentity(dir)
+    fs.writeFileSync(path.join(dir, "base.txt"), "base\n")
+    gitIn(dir, ["add", "base.txt"])
+    gitIn(dir, ["commit", "-m", "base"])
+    gitIn(dir, ["checkout", "-b", "docs/auto-sync"])
+    fs.mkdirSync(path.join(dir, "packages", "kilo-docs", "pages"), { recursive: true })
+    fs.writeFileSync(path.join(dir, "packages", "kilo-docs", "pages", "x.md"), "# x\n")
+    gitIn(dir, ["add", "packages/kilo-docs/pages/x.md"])
+    gitIn(dir, ["commit", "-m", "docs update", "--author", `kiloconnect[bot] <${kiloconnectBotEmail}>`])
+
+    // DRY_RUN=true
+    {
+      const cwd = setupLearnRepo(dir)
+      const fixturePath = writeFixture(cwd, {
+        pr: { number: 1, head: { ref: "docs/auto-sync" }, body: "", user: { login: "github-actions[bot]" } },
+        comments: [],
+      })
+
+      const kiloDir = makeStubKiloDir({ mode: "extraction-delta", callLog: path.join(cwd, "kilo-calls.log") })
+      writeExtractionDelta(cwd, { add: [], remove: [] })
+
+      const outputFile = path.join(cwd, "gh-output-q-dry")
+      const result = runNodeScript(LEARN_SCRIPT, {
+        cwd,
+        kiloDir,
+        env: {
+          TRIAGE_MODEL: "test/model",
+          DOCS_SYNC_FIXTURE: fixturePath,
+          LEARNINGS_BUDGET_MINUTES: "1",
+          DOCS_SYNC_BACKOFF_MS: "0",
+          DRY_RUN: "true",
+          GITHUB_OUTPUT: outputFile,
+        },
+      })
+
+      assert.ok(!fs.existsSync(`${fixturePath}.patched`), "DRY_RUN must suppress marker PATCH")
+      if (fs.existsSync(outputFile)) {
+        const ghOut = fs.readFileSync(outputFile, "utf8")
+        assert.ok(!ghOut.includes("learned_through="), "GITHUB_OUTPUT must not contain learned_through on DRY_RUN")
+      }
+      assert.ok(result.stdout.includes("marker PATCH suppressed"), "stdout must log marker suppression for DRY_RUN")
+      assert.ok(
+        result.stdout.includes("would have written marker"),
+        "stdout must log the suppressed marker for DRY_RUN",
+      )
+    }
+
+    // LEARNINGS_NO_PATCH=1 (same mechanism)
+    {
+      const cwd = setupLearnRepo(dir)
+      const fixturePath = writeFixture(cwd, {
+        pr: { number: 1, head: { ref: "docs/auto-sync" }, body: "", user: { login: "github-actions[bot]" } },
+        comments: [],
+      })
+
+      const kiloDir = makeStubKiloDir({ mode: "extraction-delta", callLog: path.join(cwd, "kilo-calls.log") })
+      writeExtractionDelta(cwd, { add: [], remove: [] })
+
+      const outputFile = path.join(cwd, "gh-output-q-nopatch")
+      const result = runNodeScript(LEARN_SCRIPT, {
+        cwd,
+        kiloDir,
+        env: {
+          TRIAGE_MODEL: "test/model",
+          DOCS_SYNC_FIXTURE: fixturePath,
+          LEARNINGS_BUDGET_MINUTES: "1",
+          DOCS_SYNC_BACKOFF_MS: "0",
+          LEARNINGS_NO_PATCH: "1",
+          GITHUB_OUTPUT: outputFile,
+        },
+      })
+
+      assert.ok(!fs.existsSync(`${fixturePath}.patched`), "LEARNINGS_NO_PATCH must suppress marker PATCH")
+      if (fs.existsSync(outputFile)) {
+        const ghOut = fs.readFileSync(outputFile, "utf8")
+        assert.ok(
+          !ghOut.includes("learned_through="),
+          "GITHUB_OUTPUT must not contain learned_through on LEARNINGS_NO_PATCH",
+        )
+      }
+      assert.ok(
+        result.stdout.includes("marker PATCH suppressed"),
+        "stdout must log marker suppression for LEARNINGS_NO_PATCH",
+      )
+      assert.ok(
+        result.stdout.includes("would have written marker"),
+        "stdout must log the suppressed marker for LEARNINGS_NO_PATCH",
+      )
+    }
+
+    // DRY_RUN=true with non-empty delta (suppresses learned_through output)
+    {
+      const cwd = setupLearnRepo(dir)
+      const tipSource = `commit:${gitIn(dir, ["rev-parse", "HEAD"]).slice(0, 7)}`
+      const fixturePath = writeFixture(cwd, {
+        pr: { number: 1, head: { ref: "docs/auto-sync" }, body: "", user: { login: "github-actions[bot]" } },
+        comments: [],
+      })
+
+      const kiloDir = makeStubKiloDir({ mode: "extraction-delta", callLog: path.join(cwd, "kilo-calls.log") })
+      writeExtractionDelta(cwd, {
+        add: [
+          {
+            id: "dry-suppress",
+            rule: "A rule suppressed under dry run.",
+            scope: "both",
+            source: tipSource,
+            date: "2026-08-03",
+          },
+        ],
+        remove: [],
+      })
+
+      const outputFile = path.join(cwd, "gh-output-q-dry-nonempty")
+      const result = runNodeScript(LEARN_SCRIPT, {
+        cwd,
+        kiloDir,
+        env: {
+          TRIAGE_MODEL: "test/model",
+          DOCS_SYNC_FIXTURE: fixturePath,
+          LEARNINGS_BUDGET_MINUTES: "1",
+          DOCS_SYNC_BACKOFF_MS: "0",
+          DRY_RUN: "true",
+          GITHUB_OUTPUT: outputFile,
+        },
+      })
+
+      if (fs.existsSync(outputFile)) {
+        const ghOut = fs.readFileSync(outputFile, "utf8")
+        assert.ok(
+          !ghOut.includes("learned_through="),
+          "GITHUB_OUTPUT must not contain learned_through on DRY_RUN non-empty delta",
+        )
+      }
+      assert.ok(
+        result.stdout.includes("learned-through output suppressed"),
+        "stdout must log learned-through output suppression for DRY_RUN non-empty delta",
+      )
+    }
+
+    // LEARNINGS_NO_PATCH=1 with non-empty delta
+    {
+      const cwd = setupLearnRepo(dir)
+      const tipSource = `commit:${gitIn(dir, ["rev-parse", "HEAD"]).slice(0, 7)}`
+      const fixturePath = writeFixture(cwd, {
+        pr: { number: 1, head: { ref: "docs/auto-sync" }, body: "", user: { login: "github-actions[bot]" } },
+        comments: [],
+      })
+
+      const kiloDir = makeStubKiloDir({ mode: "extraction-delta", callLog: path.join(cwd, "kilo-calls.log") })
+      writeExtractionDelta(cwd, {
+        add: [
+          {
+            id: "nopatch-suppress",
+            rule: "A rule suppressed under no-patch.",
+            scope: "both",
+            source: tipSource,
+            date: "2026-08-03",
+          },
+        ],
+        remove: [],
+      })
+
+      const outputFile = path.join(cwd, "gh-output-q-nopatch-nonempty")
+      const result = runNodeScript(LEARN_SCRIPT, {
+        cwd,
+        kiloDir,
+        env: {
+          TRIAGE_MODEL: "test/model",
+          DOCS_SYNC_FIXTURE: fixturePath,
+          LEARNINGS_BUDGET_MINUTES: "1",
+          DOCS_SYNC_BACKOFF_MS: "0",
+          LEARNINGS_NO_PATCH: "1",
+          GITHUB_OUTPUT: outputFile,
+        },
+      })
+
+      if (fs.existsSync(outputFile)) {
+        const ghOut = fs.readFileSync(outputFile, "utf8")
+        assert.ok(
+          !ghOut.includes("learned_through="),
+          "GITHUB_OUTPUT must not contain learned_through on LEARNINGS_NO_PATCH non-empty delta",
+        )
+      }
+      assert.ok(
+        result.stdout.includes("learned-through output suppressed"),
+        "stdout must log learned-through output suppression for LEARNINGS_NO_PATCH non-empty delta",
+      )
+    }
+  }
+
+  // 10s — a failed API call must not disable the existing learnings
+  // The learn step is continue-on-error, and triage and edit read only the two prompt
+  // artifacts. So learn.mjs must write them before the first call that can throw.
+  {
+    console.log("  10s — prompt artifacts survive an API failure")
+    const dir = mktemp("docs-sync-learn-s-")
+    const learningsPath = path.join(dir, "packages", "kilo-docs", "LEARNINGS.md")
+    fs.mkdirSync(path.dirname(learningsPath), { recursive: true })
+    const seeded = [
+      {
+        id: "seeded-rule",
+        rule: "Do not document features behind experimental flags.",
+        scope: "both",
+        source: "commit:aaaaaaa",
+        date: "2026-08-01",
+      },
+    ]
+    fs.writeFileSync(learningsPath, renderLearnings(seeded))
+
+    // No DOCS_SYNC_FIXTURE and an empty GITHUB_REPOSITORY: repo() throws inside
+    // extract(). It stands for any API failure before the artifacts exist.
+    const failEnv = {
+      TRIAGE_MODEL: "test/model",
+      GITHUB_REPOSITORY: "",
+      GITHUB_OUTPUT: path.join(dir, "gh-output-s"),
+      GITHUB_STEP_SUMMARY: path.join(dir, "gh-summary-s"),
+      DOCS_SYNC_BACKOFF_MS: "0",
+    }
+    const result = runNodeScript(LEARN_SCRIPT, { cwd: dir, env: failEnv })
+    assert.notEqual(result.status, 0, "extraction must fail without GITHUB_REPOSITORY")
+
+    const triagePath = path.join(dir, "docs-sync-out", "learnings-triage.md")
+    const editPath = path.join(dir, "docs-sync-out", "learnings-edit.md")
+    for (const f of [triagePath, editPath]) {
+      assert.ok(fs.existsSync(f), `${path.basename(f)} must survive the failure`)
+      assert.ok(
+        fs.readFileSync(f, "utf8").includes("Do not document features behind experimental flags."),
+        `${path.basename(f)} must carry the checked-out rule`,
+      )
+    }
+
+    // An empty file must clear the stale block, not leave the earlier rule in place.
+    fs.writeFileSync(learningsPath, renderLearnings([]))
+    runNodeScript(LEARN_SCRIPT, { cwd: dir, env: failEnv })
+    assert.ok(!fs.existsSync(triagePath), "an empty learnings file must remove learnings-triage.md")
+    assert.ok(!fs.existsSync(editPath), "an empty learnings file must remove learnings-edit.md")
+  }
+
+  // 10t — the direct marker PATCH must not overwrite a concurrent body edit
+  // The body read at step 1 predates the extraction call, so learn.mjs must re-read
+  // the body immediately before the PATCH.
+  {
+    console.log("  10t — marker PATCH preserves a concurrent body edit")
+    const dir = mktemp("docs-sync-learn-t-")
+    initRepoWithIdentity(dir)
+    fs.writeFileSync(path.join(dir, "base.txt"), "base\n")
+    gitIn(dir, ["add", "base.txt"])
+    gitIn(dir, ["commit", "-m", "base"])
+    gitIn(dir, ["checkout", "-b", "docs/auto-sync"])
+
+    // github-actions[bot] authored the only branch commit, so there is no candidate
+    // correction and no model call. The run goes straight to the direct marker PATCH.
+    const learningsPath = path.join(dir, "packages", "kilo-docs", "LEARNINGS.md")
+    fs.mkdirSync(path.dirname(learningsPath), { recursive: true })
+    fs.writeFileSync(learningsPath, renderLearnings([]))
+    gitIn(dir, ["add", "packages/kilo-docs/LEARNINGS.md"])
+    gitIn(dir, ["commit", "-m", "seed learnings", "--author", `github-actions[bot] <${githubBotEmail}>`])
+    gitIn(dir, ["remote", "add", "origin", dir]) // learn.mjs fetches origin itself
+    const cwd = setupLearnRepo(dir)
+    const tip = gitIn(dir, ["rev-parse", "HEAD"])
+
+    // Stub GitHub API. The second read of the pull request returns the maintainer edit.
+    const serverDir = mktemp("docs-sync-api-t-")
+    const portFile = path.join(serverDir, "port")
+    const patchFile = path.join(serverDir, "patch.json")
+    const serverScript = path.join(serverDir, "server.cjs")
+    fs.writeFileSync(
+      serverScript,
+      `const fs = require("node:fs")
+const http = require("node:http")
+let reads = 0
+const json = (res, data) => {
+  res.writeHead(200, { "content-type": "application/json" })
+  res.end(JSON.stringify(data))
+}
+const server = http.createServer((req, res) => {
+  let raw = ""
+  req.on("data", (c) => (raw += c))
+  req.on("end", () => {
+    if (req.method === "PATCH") return fs.writeFileSync(process.env.PATCH_FILE, raw), json(res, {})
+    if (req.url.startsWith("/search/issues")) return json(res, { items: [{ number: 1 }] })
+    if (req.url.includes("/comments")) return json(res, [])
+    if (req.url.includes("/pulls/1")) {
+      const body = reads++ === 0 ? process.env.BODY_BEFORE : process.env.BODY_AFTER
+      return json(res, {
+        number: 1,
+        body,
+        head: { ref: "docs/auto-sync" },
+        user: { login: "github-actions[bot]" },
+      })
+    }
+    json(res, {})
+  })
+})
+server.listen(0, "127.0.0.1", () => fs.writeFileSync(process.env.PORT_FILE, String(server.address().port)))
+`,
+    )
+
+    const bodyBefore = "Rolling PR body.\n<!-- docs-sync: learned-through commit=old comment=none -->\n"
+    const humanEdit = "A maintainer edited the body while extraction ran."
+    const child = spawn(process.execPath, [serverScript], {
+      stdio: "ignore",
+      env: {
+        ...process.env,
+        PORT_FILE: portFile,
+        PATCH_FILE: patchFile,
+        BODY_BEFORE: bodyBefore,
+        BODY_AFTER: bodyBefore + humanEdit + "\n",
+      },
+    })
+
+    try {
+      let port = ""
+      for (let i = 0; i < 100 && !port; i++) {
+        if (fs.existsSync(portFile)) port = fs.readFileSync(portFile, "utf8").trim()
+        else sleepSync(50)
+      }
+      assert.ok(port, "the stub API server must report a port")
+
+      const result = runNodeScript(LEARN_SCRIPT, {
+        cwd,
+        env: {
+          TRIAGE_MODEL: "test/model",
+          GITHUB_REPOSITORY: "acme/repo",
+          GH_TOKEN: "stub-token",
+          DOCS_SYNC_API_BASE: `http://127.0.0.1:${port}`,
+          GITHUB_OUTPUT: path.join(dir, "gh-output-t"),
+          GITHUB_STEP_SUMMARY: path.join(dir, "gh-summary-t"),
+          LEARNINGS_BUDGET_MINUTES: "1",
+          DOCS_SYNC_BACKOFF_MS: "0",
+        },
+      })
+      assert.equal(result.status, 0, `learn.mjs must succeed against the stub API: ${result.output}`)
+
+      assert.ok(fs.existsSync(patchFile), "the run must PATCH the pull request body")
+      const patchedBody = JSON.parse(fs.readFileSync(patchFile, "utf8")).body
+      assert.ok(patchedBody.includes(humanEdit), "the concurrent body edit must survive the marker PATCH")
+      assert.ok(patchedBody.includes(tip), "the PATCH must carry the new tip SHA")
+      assert.ok(!patchedBody.includes("commit=old"), "the old marker must be replaced")
+      assert.equal(
+        (patchedBody.match(/<!--\s*docs-sync:\s*learned-through/g) || []).length,
+        1,
+        "exactly one marker after the PATCH",
+      )
+    } finally {
+      child.kill()
+    }
+  }
+
+  // 10u — one model response cannot repeat an id or a rule
+  {
+    console.log("  10u — duplicates inside one delta")
+    const base = { scope: "both", source: "commit:aaaaaaa", date: "2026-08-03" }
+    const ctx = { existing: [], candidateSources: ["commit:aaaaaaa"], deletedInWindow: [] }
+
+    const dupId = validateDelta(
+      {
+        add: [
+          { ...base, id: "same-id", rule: "Do not document features behind experimental flags." },
+          { ...base, id: "same-id", rule: "Keep the release notes short." },
+        ],
+        remove: [],
+      },
+      ctx,
+    )
+    assert.equal(dupId.add.length, 1, "a repeated id must be rejected")
+    assert.equal(dupId.add[0].rule, "Do not document features behind experimental flags.")
+    assert.equal(dupId.rejected.length, 1)
+    assert.ok(dupId.rejected[0].reason.includes("earlier addition"), "the reason must name the earlier addition")
+
+    const dupText = validateDelta(
+      {
+        add: [
+          { ...base, id: "rule-one", rule: "Do not document features behind experimental flags." },
+          { ...base, id: "rule-two", rule: "Do not document features behind experimental flags!" },
+        ],
+        remove: [],
+      },
+      ctx,
+    )
+    assert.equal(dupText.add.length, 1, "a repeated rule text must be rejected")
+    assert.equal(dupText.rejected.length, 1)
+    assert.ok(dupText.rejected[0].reason.includes("earlier addition"), "the reason must name the earlier addition")
+  }
+
+  // Prompt block format
+  {
+    console.log("  10 — promptBlock format")
+    const entries = [
+      { id: "r1", rule: "First rule.", scope: "triage", source: "commit:aaaaaaa", date: "2026-08-01" },
+      { id: "r2", rule: "Second rule.", scope: "edit", source: "commit:bbbbbbb", date: "2026-08-02" },
+      { id: "r3", rule: "Both rule.", scope: "both", source: "commit:ccccccc", date: "2026-08-03" },
+    ]
+
+    const triageBlock = promptBlock(entries, "triage")
+    assert.ok(triageBlock.includes("First rule"), "triage block must include triage-scoped rule")
+    assert.ok(triageBlock.includes("Both rule"), "triage block must include both-scoped rule")
+    assert.ok(!triageBlock.includes("Second rule"), "triage block must not include edit-only rule")
+    assert.ok(triageBlock.includes("## Learnings from maintainer corrections"))
+
+    const editBlock = promptBlock(entries, "edit")
+    assert.ok(editBlock.includes("Second rule"), "edit block must include edit-scoped rule")
+    assert.ok(editBlock.includes("Both rule"), "edit block must include both-scoped rule")
+    assert.ok(!editBlock.includes("First rule"), "edit block must not include triage-only rule")
+
+    // Empty: no matching entries
+    const emptyBlock = promptBlock(
+      [{ id: "r1", rule: "R.", scope: "edit", source: "commit:aa", date: "2026-01-01" }],
+      "triage",
+    )
+    assert.equal(emptyBlock, "")
+  }
+
+  // parseLearnedThrough
+  {
+    console.log("  10 — parseLearnedThrough")
+    const body = "stuff\n<!-- docs-sync: learned-through commit=abc1234 comment=2026-08-03T12:00:00Z -->\nmore"
+    const parsed = parseLearnedThrough(body)
+    assert.equal(parsed.commit, "abc1234")
+    assert.equal(parsed.comment, "2026-08-03T12:00:00Z")
+
+    // none values → null
+    const noneBody = "<!-- docs-sync: learned-through commit=none comment=none -->"
+    const noneParsed = parseLearnedThrough(noneBody)
+    assert.equal(noneParsed.commit, null)
+    assert.equal(noneParsed.comment, null)
+
+    // absent → both null
+    const absent = parseLearnedThrough("no marker")
+    assert.equal(absent.commit, null)
+    assert.equal(absent.comment, null)
+  }
+
+  // renderLearnings deterministic order
+  {
+    console.log("  10 — renderLearnings deterministic order")
+    const entries = [
+      { id: "b", rule: "B rule.", scope: "both", source: "commit:bb", date: "2026-08-02" },
+      { id: "a", rule: "A rule.", scope: "both", source: "commit:aa", date: "2026-08-01" },
+      { id: "c", rule: "C rule.", scope: "both", source: "commit:cc", date: "2026-08-01" },
+    ]
+    const r1 = renderLearnings(entries)
+    const r2 = renderLearnings(entries)
+    assert.equal(r1, r2, "renderLearnings must be deterministic")
+    // Order: date ascending, then id ascending. So a before b before c (a.date < c.date, both before b)
+    const aPos = r1.indexOf("A rule")
+    const cPos = r1.indexOf("C rule")
+    const bPos = r1.indexOf("B rule")
+    assert.ok(aPos < cPos, "a (earlier date) must come before c")
+    assert.ok(cPos < bPos, "c (same date as a but later id) must come before b (later date)")
+  }
+}
+
+// Case 11 — the created rolling PR gets an assignee and a review request
+function case11_prOwner() {
+  console.log("case 11 — created PR assignee and reviewer")
+  const src = fs.readFileSync(path.join(HERE, "upsert-pr.mjs"), "utf8")
+
+  assert.ok(/const DOCS_OWNER = "\S+"/.test(src), "DOCS_OWNER must be a module constant")
+  assert.ok(src.includes("/assignees`, {"), "created PR must POST assignees")
+  assert.ok(src.includes("/requested_reviewers`, {"), "created PR must POST requested_reviewers")
+
+  // Both calls belong to the create arm, after the PR exists.
+  const createIdx = src.indexOf("const pr = await api(`/repos/${repo()}/pulls`")
+  assert.ok(createIdx >= 0, "create-PR call must exist")
+  assert.ok(src.indexOf("/assignees`, {") > createIdx, "assignees POST must follow PR creation")
+  assert.ok(src.indexOf("/requested_reviewers`, {") > createIdx, "reviewer POST must follow PR creation")
+
+  // A failure here must not fail the run — the PR is already open.
+  const ownerIdx = src.indexOf("/assignees`, {")
+  const tryIdx = src.lastIndexOf("try {", ownerIdx)
+  const catchIdx = src.indexOf("} catch", ownerIdx)
+  assert.ok(tryIdx >= 0 && catchIdx > src.indexOf("/requested_reviewers`, {"), "both POSTs must sit in one try/catch")
+}
+
 // ---------------------------------------------------------------------------
 // main
 // ---------------------------------------------------------------------------
@@ -1846,6 +3473,8 @@ function main() {
     case7_cap,
     case8_triage,
     case9_reverts,
+    case10_learnings,
+    case11_prOwner,
   ]
   let failed = 0
   for (const fn of cases) {
diff --git a/.github/docs-sync/triage.mjs b/.github/docs-sync/triage.mjs
index a01eef0a998..eb680846510 100644
--- a/.github/docs-sync/triage.mjs
+++ b/.github/docs-sync/triage.mjs
@@ -21,6 +21,7 @@ import path from "node:path"
 import { fileURLToPath } from "node:url"
 import { parseTriageEntries } from "./extract-json.mjs"
 import { appendSummary, backoffMsForAttempt, deadline, remainingMs, runKilo, sleepSync } from "./lib.mjs"
+import { readLearningsBlock } from "./learn.mjs"
 
 const CHUNK_SIZE = 25
 const ATTEMPTS = 3
@@ -28,7 +29,7 @@ const OUT_DIR = "docs-sync-out"
 const CHUNK_TIMEOUT_MS = 10 * 60 * 1000
 
 const HERE = path.dirname(fileURLToPath(import.meta.url))
-const prompt = fs.readFileSync(path.join(HERE, "triage-prompt.md"), "utf8")
+const prompt = fs.readFileSync(path.join(HERE, "triage-prompt.md"), "utf8") + readLearningsBlock("triage")
 const model = process.env.TRIAGE_MODEL
 if (!model) throw new Error("TRIAGE_MODEL is required")
 
@@ -115,9 +116,7 @@ function triageChunk(chunk, index, budgetDeadline) {
         console.warn(`chunk ${index}: backing off ${wait / 1000}s before attempt ${attempt + 1}`)
         sleepSync(wait)
       } else if (wait > 0) {
-        console.warn(
-          `chunk ${index}: skipping backoff — remaining budget cannot fit attempt ${attempt + 1} after wait`,
-        )
+        console.warn(`chunk ${index}: skipping backoff — remaining budget cannot fit attempt ${attempt + 1} after wait`)
       }
     }
   }
@@ -125,7 +124,12 @@ function triageChunk(chunk, index, budgetDeadline) {
   console.warn(
     `::warning::chunk ${index} failed triage after up to ${ATTEMPTS} attempts; marking ${chunk.length} PRs pending`,
   )
-  return chunk.map((d) => pendingEntry(d, lastCause.includes("triage failed") ? lastCause : `triage failed to classify this PR (${lastCause})`))
+  return chunk.map((d) =>
+    pendingEntry(
+      d,
+      lastCause.includes("triage failed") ? lastCause : `triage failed to classify this PR (${lastCause})`,
+    ),
+  )
 }
 
 const chunks = []
diff --git a/.github/docs-sync/upsert-pr.mjs b/.github/docs-sync/upsert-pr.mjs
index 1ef25b75964..d4b7d2a21fc 100644
--- a/.github/docs-sync/upsert-pr.mjs
+++ b/.github/docs-sync/upsert-pr.mjs
@@ -27,15 +27,23 @@ const FILE_CAP = 15
 const ROW_CAP = 150
 const PENDING_DISPLAY_CAP = 60
 const SUMMARY_FILE = ".docs-sync-summary.json"
+// Owner of the rolling docs PR: assigned and asked for review on creation.
+const DOCS_OWNER = "emilieschario"
 const DOCS_PATH = "packages/kilo-docs"
+export const LEARNINGS_FILE = "packages/kilo-docs/LEARNINGS.md"
 
-const git = (args) => execFileSync("git", args, { stdio: ["ignore", "pipe", "inherit"] }).toString().trim()
+const git = (args) =>
+  execFileSync("git", args, { stdio: ["ignore", "pipe", "inherit"] })
+    .toString()
+    .trim()
 
 // Agent-generated strings land in the PR body next to machine-read markers.
 // Strip HTML-comment sequences so a crafted/adversarial value cannot forge
 // section boundaries or the processed-through watermark.
 function clean(value) {
-  return String(value ?? "").replaceAll("<!--", "").replaceAll("-->", "")
+  return String(value ?? "")
+    .replaceAll("<!--", "")
+    .replaceAll("-->", "")
 }
 
 function shortRef(url) {
@@ -52,7 +60,9 @@ function skippedRow(e) {
 }
 
 function pendingRow(e) {
-  const reason = clean(e.reason ?? e.cause ?? "").replaceAll("|", "\\|").replaceAll("\n", " ")
+  const reason = clean(e.reason ?? e.cause ?? "")
+    .replaceAll("|", "\\|")
+    .replaceAll("\n", " ")
   return `| [${shortRef(e.url)}](${clean(e.url)}) | ${reason} |`
 }
 
@@ -79,7 +89,18 @@ function section(name, header, rows) {
   return `<!-- docs-sync:${name}:start -->\n${body}\n<!-- docs-sync:${name}:end -->`
 }
 
-export function renderBody({ date, since, through, changesRows, pendingRows, skippedRows, verified, draftReasons, note }) {
+export function renderBody({
+  date,
+  since,
+  through,
+  learnedThrough = "",
+  changesRows,
+  pendingRows,
+  skippedRows,
+  verified,
+  draftReasons,
+  note,
+}) {
   const pendingDisplay =
     pendingRows.length > PENDING_DISPLAY_CAP
       ? [...pendingRows.slice(0, PENDING_DISPLAY_CAP), `| +${pendingRows.length - PENDING_DISPLAY_CAP} more | |`]
@@ -108,7 +129,7 @@ ${section("skipped", "| PR | Reason |", skippedRows)}
 
 (bot) Generated by the docs-sync workflow. Humans review and merge; while this PR stays open, the next daily run appends new changes here. Branch: \`${BRANCH}\`.
 <!-- docs-sync: processed-through ${through} -->
-`
+${learnedThrough ? learnedThrough + "\n" : ""}`
 }
 
 function mergeRows(oldRows, newRows) {
@@ -242,6 +263,23 @@ export function computeProcessedThrough({ uncovered, digest, now, fallback }) {
   return new Date(earliest - 1).toISOString()
 }
 
+/**
+ * Content gate: legitimate bot edits are docs pages and nav files. Only
+ * those are built and tested during verify (content-integrity.test.ts
+ * walks pages/ only), so anything else in the docs package forces human
+ * review. LEARNINGS.md is a root-level .md file, like the three sibling
+ * .md files already at that level, so it is not built or tested and is
+ * safe to exclude from the gate.
+ */
+export function nonContentFiles(changedFiles) {
+  return (Array.isArray(changedFiles) ? changedFiles : []).filter(
+    (f) =>
+      f !== LEARNINGS_FILE &&
+      !f.startsWith("packages/kilo-docs/pages/") &&
+      !f.startsWith("packages/kilo-docs/lib/nav/"),
+  )
+}
+
 /**
  * Route summary + triage into the three body sections.
  * changesRows = action neither skipped nor pending
@@ -280,6 +318,22 @@ export function dropLegacySkipped(rows) {
   })
 }
 
+/**
+ * Resolve the learned-through marker for renderBody.
+ *
+ * Order: env LEARNED_THROUGH when set and non-empty; else the marker
+ * parsed out of the existing PR body; else "".
+ * The fallback is load-bearing: a run where extraction was skipped,
+ * failed, or already PATCHed the marker itself must not clobber a good
+ * marker.
+ */
+export function resolveLearnedThrough({ envValue, prBody }) {
+  const fromEnv = String(envValue ?? "").trim()
+  if (fromEnv) return fromEnv
+  const m = String(prBody ?? "").match(/<!--\s*docs-sync:\s*learned-through\s+commit=\S+\s+comment=\S+\s*-->/)
+  return m ? m[0] : ""
+}
+
 /**
  * No-diff early-return report. Returns summary markdown and an optional
  * replay warning. Warns IFF sinceOverride && uncovered non-empty (no commit
@@ -347,18 +401,14 @@ async function main() {
   const through = computeProcessedThrough({ uncovered, digest, now, fallback: since })
 
   // The draft cap bounds the cumulative PR diff, not just this run's commit.
-  const changedFiles = git(["diff", "--name-only", "origin/main...HEAD", "--", DOCS_PATH])
-    .split("\n")
-    .filter(Boolean)
+  const changedFiles = git(["diff", "--name-only", "origin/main...HEAD", "--", DOCS_PATH]).split("\n").filter(Boolean)
   const draftReasons = []
   if (changedFiles.length > FILE_CAP) draftReasons.push(`diff exceeds ${FILE_CAP} files (${changedFiles.length})`)
   if (!verified) draftReasons.push("docs build/tests not passing")
   // Content gate: legitimate bot edits are docs pages and nav files. Anything
   // else in the docs package (build config, components, tests) executes
   // during the verify build, so force human review before merge.
-  const nonContent = changedFiles.filter(
-    (f) => !f.startsWith("packages/kilo-docs/pages/") && !f.startsWith("packages/kilo-docs/lib/nav/"),
-  )
+  const nonContent = nonContentFiles(changedFiles)
   if (nonContent.length > 0) {
     // File paths are agent-chosen; sanitize before they land in the PR body.
     const listed = nonContent
@@ -369,9 +419,17 @@ async function main() {
   }
   const draft = draftReasons.length > 0
 
-  git(mode === "update" ? ["push", "origin", `HEAD:${BRANCH}`] : ["push", "--force-with-lease", "origin", `HEAD:${BRANCH}`])
+  git(
+    mode === "update"
+      ? ["push", "origin", `HEAD:${BRANCH}`]
+      : ["push", "--force-with-lease", "origin", `HEAD:${BRANCH}`],
+  )
 
-  const { changesRows: changesNew, pendingRows: pendingNew, skippedRows: skippedNew } = routeRows({
+  const {
+    changesRows: changesNew,
+    pendingRows: pendingNew,
+    skippedRows: skippedNew,
+  } = routeRows({
     summary: agentSummary,
     triage,
     uncovered,
@@ -380,8 +438,10 @@ async function main() {
   let oldChanges = []
   let oldSkipped = []
   let oldPending = []
+  let prBody = ""
   if (mode === "update" && existingPr) {
     const pr = await api(`/repos/${repo()}/pulls/${existingPr}`)
+    prBody = pr.body ?? ""
     oldChanges = extractSectionRows(pr.body, "changes")
     oldSkipped = dropLegacySkipped(extractSectionRows(pr.body, "skipped"))
     oldPending = extractSectionRows(pr.body, "pending")
@@ -392,10 +452,13 @@ async function main() {
   // extractSectionRows stays exercised; discarded deliberately.
   void oldPending
 
+  const learnedThrough = resolveLearnedThrough({ envValue: process.env.LEARNED_THROUGH, prBody })
+
   const body = renderBody({
     date,
     since,
     through,
+    learnedThrough,
     changesRows: mergeRows(oldChanges, changesNew),
     pendingRows: pendingNew,
     skippedRows: mergeRows(oldSkipped, skippedNew),
@@ -445,6 +508,20 @@ async function main() {
     prNumber = pr.number
     prUrl = pr.html_url
     await api(`/repos/${repo()}/issues/${prNumber}/labels`, { method: "POST", body: { labels: ["auto-docs"] } })
+    // Best effort: the PR already exists here, so a non-collaborator or a
+    // revoked account must not fail the run.
+    try {
+      await api(`/repos/${repo()}/issues/${prNumber}/assignees`, {
+        method: "POST",
+        body: { assignees: [DOCS_OWNER] },
+      })
+      await api(`/repos/${repo()}/pulls/${prNumber}/requested_reviewers`, {
+        method: "POST",
+        body: { reviewers: [DOCS_OWNER] },
+      })
+    } catch (err) {
+      console.warn(`::warning::docs-sync: could not assign or request review from ${DOCS_OWNER}: ${err.message}`)
+    }
     if (mode === "conflict" && existingPr) {
       await api(`/repos/${repo()}/issues/${existingPr}/comments`, {
         method: "POST",
@@ -459,7 +536,9 @@ async function main() {
   appendSummary(
     `### docs-sync PR\n\n- ${prUrl}\n- changed files: ${changedFiles.length}\n- draft: ${draft}\n- uncovered: ${uncovered.length}\n- processed-through: ${through}\n`,
   )
-  console.log(`PR ${prNumber}: ${prUrl} (draft=${draft}, files=${changedFiles.length}, uncovered=${uncovered.length}, through=${through})`)
+  console.log(
+    `PR ${prNumber}: ${prUrl} (draft=${draft}, files=${changedFiles.length}, uncovered=${uncovered.length}, through=${through})`,
+  )
 }
 
 const isMain = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href
diff --git a/.github/workflows/docs-sync.yml b/.github/workflows/docs-sync.yml
index 147cde8a474..1ae78f3edb4 100644
--- a/.github/workflows/docs-sync.yml
+++ b/.github/workflows/docs-sync.yml
@@ -66,13 +66,13 @@ jobs:
   sync:
     if: github.repository == 'Kilo-Org/kilocode' && github.event_name != 'pull_request'
     runs-on: blacksmith-4vcpu-ubuntu-2404
-    # Budget: 4 setup/collect + 90 triage + 120 edit + 2 verify + 10 fix + 2 upsert = 228 min, 12-minute reserve.
+    # Budget: 4 setup/collect + 10 learn + 90 triage + 120 edit + 2 verify + 10 fix + 2 upsert = 238 min, 12-minute reserve.
     # These are ceilings, not costs: a caught-up run triages ~2 chunks and edits
     # ~1 batch and finishes in ~25 min. The old 35/50 pair was the binding
     # constraint on backlog drain — run 30306629290 deferred 54 PRs untriaged and
     # 31 unedited purely on budget, with no attempt made. See the throughput note
     # in the PR description for the arithmetic.
-    timeout-minutes: 240
+    timeout-minutes: 250
     env:
       # Both are required: without KILO_ORG_ID the gateway bills the key
       # owner's personal balance (402 "Add credits") instead of the org.
@@ -110,6 +110,15 @@ jobs:
           INPUT_SINCE: ${{ inputs.since }}
         run: node .github/docs-sync/watermark.mjs
 
+      - name: Learn from maintainer corrections
+        id: learn
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ github.token }}
+          LEARNINGS_BUDGET_MINUTES: "10"
+          DRY_RUN: ${{ inputs.dry_run }}
+        run: node .github/docs-sync/learn.mjs
+
       - name: Collect merged PRs
         id: collect
         env:
@@ -215,10 +224,15 @@ jobs:
             echo "ok=false" >> "$GITHUB_OUTPUT"
           fi
 
+      - name: Write the learnings file
+        if: (steps.worthy.outputs.count || '0') != '0' && inputs.dry_run != true
+        run: node .github/docs-sync/learn.mjs --apply
+
       - name: Upsert rolling PR
         if: (steps.worthy.outputs.count || '0') != '0' && inputs.dry_run != true
         env:
           GH_TOKEN: ${{ github.token }}
+          LEARNED_THROUGH: ${{ steps.learn.outputs.learned_through }}
           PROCESSED_THROUGH: ${{ steps.wm.outputs.now }}
           SINCE: ${{ steps.wm.outputs.since }}
           SINCE_OVERRIDE: ${{ steps.wm.outputs.since_override }}
diff --git a/bun.lock b/bun.lock
index e2b68afdf4f..67811a9f0ef 100644
--- a/bun.lock
+++ b/bun.lock
@@ -32,7 +32,7 @@
     },
     "packages/core": {
       "name": "@opencode-ai/core",
-      "version": "7.4.18",
+      "version": "7.4.20",
       "bin": {
         "opencode": "./bin/opencode",
       },
@@ -127,7 +127,7 @@
     },
     "packages/effect-drizzle-sqlite": {
       "name": "@opencode-ai/effect-drizzle-sqlite",
-      "version": "7.4.18",
+      "version": "7.4.20",
       "dependencies": {
         "drizzle-orm": "catalog:",
         "effect": "catalog:",
@@ -141,7 +141,7 @@
     },
     "packages/effect-sqlite-node": {
       "name": "@opencode-ai/effect-sqlite-node",
-      "version": "7.4.18",
+      "version": "7.4.20",
       "dependencies": {
         "effect": "catalog:",
       },
@@ -153,7 +153,7 @@
     },
     "packages/http-recorder": {
       "name": "@opencode-ai/http-recorder",
-      "version": "7.4.18",
+      "version": "7.4.20",
       "dependencies": {
         "@effect/platform-node": "4.0.0-beta.74",
         "@effect/platform-node-shared": "4.0.0-beta.74",
@@ -174,7 +174,7 @@
     },
     "packages/kilo-console": {
       "name": "@kilocode/kilo-console",
-      "version": "7.4.18",
+      "version": "7.4.20",
       "dependencies": {
         "@kilocode/kilo-indexing": "workspace:*",
         "@kilocode/kilo-web-ui": "workspace:*",
@@ -197,7 +197,7 @@
     },
     "packages/kilo-docs": {
       "name": "@kilocode/kilo-docs",
-      "version": "7.4.18",
+      "version": "7.4.20",
       "dependencies": {
         "@docsearch/css": "^4",
         "@docsearch/js": "^4",
@@ -227,7 +227,7 @@
     },
     "packages/kilo-gateway": {
       "name": "@kilocode/kilo-gateway",
-      "version": "7.4.18",
+      "version": "7.4.20",
       "dependencies": {
         "@ai-sdk/alibaba": "1.0.17",
         "@ai-sdk/anthropic": "3.0.82",
@@ -263,7 +263,7 @@
     },
     "packages/kilo-i18n": {
       "name": "@kilocode/kilo-i18n",
-      "version": "7.4.18",
+      "version": "7.4.20",
       "devDependencies": {
         "@tsconfig/node22": "catalog:",
         "@types/bun": "catalog:",
@@ -273,7 +273,7 @@
     },
     "packages/kilo-indexing": {
       "name": "@kilocode/kilo-indexing",
-      "version": "7.4.18",
+      "version": "7.4.20",
       "dependencies": {
         "@aws-sdk/client-bedrock-runtime": "3.1005.0",
         "@aws-sdk/credential-provider-ini": "3.972.31",
@@ -309,7 +309,7 @@
     },
     "packages/kilo-memory": {
       "name": "@kilocode/kilo-memory",
-      "version": "7.4.18",
+      "version": "7.4.20",
       "dependencies": {
         "effect": "catalog:",
         "zod": "catalog:",
@@ -323,7 +323,7 @@
     },
     "packages/kilo-sandbox": {
       "name": "@kilocode/sandbox",
-      "version": "7.4.18",
+      "version": "7.4.20",
       "dependencies": {
         "@anthropic-ai/sandbox-runtime": "catalog:",
         "effect": "catalog:",
@@ -338,7 +338,7 @@
     },
     "packages/kilo-telemetry": {
       "name": "@kilocode/kilo-telemetry",
-      "version": "7.4.18",
+      "version": "7.4.20",
       "dependencies": {
         "@kilocode/kilo-gateway": "workspace:*",
         "posthog-node": "4.4.0",
@@ -352,7 +352,7 @@
     },
     "packages/kilo-ui": {
       "name": "@kilocode/kilo-ui",
-      "version": "7.4.18",
+      "version": "7.4.20",
       "dependencies": {
         "@kilocode/sdk": "workspace:*",
         "@kobalte/core": "0.13.11",
@@ -390,7 +390,7 @@
     },
     "packages/kilo-vscode": {
       "name": "kilo-code",
-      "version": "7.4.18",
+      "version": "7.4.20",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.39.0",
         "@kilocode/kilo-gateway": "workspace:*",
@@ -459,7 +459,7 @@
     },
     "packages/kilo-web-ui": {
       "name": "@kilocode/kilo-web-ui",
-      "version": "7.4.18",
+      "version": "7.4.20",
       "dependencies": {
         "@kilocode/kilo-ui": "workspace:*",
         "@kobalte/core": "catalog:",
@@ -476,7 +476,7 @@
     },
     "packages/llm": {
       "name": "@opencode-ai/llm",
-      "version": "7.4.18",
+      "version": "7.4.20",
       "dependencies": {
         "@smithy/eventstream-codec": "4.2.14",
         "@smithy/util-utf8": "4.2.2",
@@ -494,7 +494,7 @@
     },
     "packages/opencode": {
       "name": "@kilocode/cli",
-      "version": "7.4.18",
+      "version": "7.4.20",
       "bin": {
         "kilo": "./bin/kilo",
         "kilocode": "./bin/kilo",
@@ -661,7 +661,7 @@
     },
     "packages/plugin": {
       "name": "@kilocode/plugin",
-      "version": "7.4.18",
+      "version": "7.4.20",
       "dependencies": {
         "@kilocode/sdk": "workspace:*",
         "effect": "catalog:",
@@ -689,7 +689,7 @@
     },
     "packages/plugin-atomic-chat": {
       "name": "@kilocode/plugin-atomic-chat",
-      "version": "7.4.18",
+      "version": "7.4.20",
       "dependencies": {
         "@kilocode/plugin": "workspace:*",
       },
@@ -703,7 +703,7 @@
     },
     "packages/script": {
       "name": "@opencode-ai/script",
-      "version": "7.4.18",
+      "version": "7.4.20",
       "dependencies": {
         "semver": "^7.6.3",
       },
@@ -714,7 +714,7 @@
     },
     "packages/sdk/js": {
       "name": "@kilocode/sdk",
-      "version": "7.4.18",
+      "version": "7.4.20",
       "dependencies": {
         "cross-spawn": "catalog:",
       },
@@ -729,7 +729,7 @@
     },
     "packages/server": {
       "name": "@opencode-ai/server",
-      "version": "7.4.18",
+      "version": "7.4.20",
       "dependencies": {
         "@opencode-ai/core": "workspace:*",
         "drizzle-orm": "catalog:",
@@ -743,7 +743,7 @@
     },
     "packages/storybook": {
       "name": "@opencode-ai/storybook",
-      "version": "7.4.18",
+      "version": "7.4.20",
       "devDependencies": {
         "@opencode-ai/ui": "workspace:*",
         "@solidjs/meta": "catalog:",
@@ -766,7 +766,7 @@
     },
     "packages/tui": {
       "name": "@opencode-ai/tui",
-      "version": "7.4.18",
+      "version": "7.4.20",
       "dependencies": {
         "@kilocode/plugin": "workspace:*",
         "@kilocode/sdk": "workspace:*",
@@ -793,7 +793,7 @@
     },
     "packages/ui": {
       "name": "@opencode-ai/ui",
-      "version": "7.4.18",
+      "version": "7.4.20",
       "dependencies": {
         "@kilocode/sdk": "workspace:*",
         "@kobalte/core": "catalog:",
diff --git a/package.json b/package.json
index cb7a4a91b07..e55aa0cf85f 100644
--- a/package.json
+++ b/package.json
@@ -173,6 +173,6 @@
     "pacote@21.5.1": "patches/pacote@21.5.1.patch",
     "mammoth@1.12.0": "patches/mammoth@1.12.0.patch"
   },
-  "version": "7.4.18",
+  "version": "7.4.20",
   "peerDependencies": {}
 }
diff --git a/packages/core/package.json b/packages/core/package.json
index e07c580a5de..a5e0eb65ff1 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -1,6 +1,6 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
-  "version": "7.4.18",
+  "version": "7.4.20",
   "name": "@opencode-ai/core",
   "type": "module",
   "license": "MIT",
diff --git a/packages/core/src/filesystem/search.ts b/packages/core/src/filesystem/search.ts
index 93833414265..647470686af 100644
--- a/packages/core/src/filesystem/search.ts
+++ b/packages/core/src/filesystem/search.ts
@@ -1,7 +1,7 @@
 export * as FileSystemSearch from "./search"
 
 import path from "path"
-import { Context, Effect, Layer, Scope } from "effect"
+import { Context, Duration, Effect, Layer, Scope } from "effect"
 import { Fff } from "#fff"
 import fuzzysort from "fuzzysort"
 import { FileSystem } from "../filesystem"
@@ -77,7 +77,8 @@ export const ripgrepLayer = Layer.effect(
             })
             .pipe(
               Effect.map((result) =>
-                result.items.map( // kilocode_change
+                result.items.map(
+                  // kilocode_change
                   (entry) =>
                     new FileSystem.Entry({
                       ...entry,
@@ -105,7 +106,8 @@ export const ripgrepLayer = Layer.effect(
             })
             .pipe(
               Effect.map((result) =>
-                result.items.map( // kilocode_change
+                result.items.map(
+                  // kilocode_change
                   (match) =>
                     new FileSystem.Match({
                       ...match,
@@ -166,27 +168,65 @@ export const fffLayer = Layer.effect(
       return real !== undefined && FSUtil.contains(root.path, real)
     })
     // kilocode_change end
-    const result = yield* Effect.try({
-      try: () =>
-        Fff.create({
-          basePath: location.directory,
-          aiMode: true,
-          ...scanning(location.directory), // kilocode_change - permit broad scanning only at the exact boundary.
-        }),
-      catch: (cause) => cause,
-    }).pipe(Effect.orDie)
-    if (!result.ok) return yield* Effect.die(result.error)
-    yield* Effect.addFinalizer(() => Effect.sync(() => result.value.destroy()).pipe(Effect.ignore))
+    // kilocode_change start - defer FFF until search because other location consumers do not need its native index.
+    const scope = yield* Scope.Scope
+    const release = (entry: { finder: { destroy(): void }; closed: boolean }) =>
+      Effect.sync(() => {
+        if (entry.closed) return
+        entry.closed = true
+        entry.finder.destroy()
+      }).pipe(Effect.ignore)
+    const make = Effect.uninterruptible(
+      Effect.gen(function* () {
+        const result = yield* Effect.try({
+          try: () =>
+            Fff.create({
+              basePath: location.directory,
+              aiMode: true,
+              disableMmapCache: true,
+              disableContentIndexing: true,
+              ...scanning(location.directory),
+            }),
+          catch: (cause) => cause,
+        }).pipe(Effect.orDie)
+        if (!result.ok) return yield* Effect.die(result.error)
+        const entry = { finder: result.value, closed: false }
+        yield* Scope.addFinalizer(scope, release(entry))
+        return entry
+      }),
+    )
+    const [load, invalidate] = yield* Effect.cachedInvalidateWithTTL(
+      make.pipe(
+        Effect.flatMap((entry) =>
+          Effect.promise(() => entry.finder.waitForScan())
+            .pipe(
+              Effect.orDie,
+              Effect.onError(() => release(entry)),
+            )
+            .pipe(
+              Effect.flatMap((scan) => {
+                if (!scan.ok || !scan.value) return Effect.die(new Error("FFF initial scan did not complete"))
+                return Effect.succeed(entry)
+              }),
+            ),
+        ),
+      ),
+      Duration.infinity,
+    )
+    const get = load.pipe(Effect.onError(() => invalidate))
+    yield* Scope.addFinalizer(scope, invalidate)
+    // kilocode_change end
     return Service.of({
       glob: (input) =>
         // kilocode_change start
         Effect.gen(function* () {
           const { root, target } = yield* inspect(input.path)
-        // kilocode_change end
+          const result = yield* get
+          // kilocode_change end
           const prefix = input.path?.replaceAll("\\", "/").replace(/\/$/, "")
           // kilocode_change start
           const found = yield* Effect.sync(() =>
-            result.value.glob(prefix ? `${prefix}/${input.pattern}` : input.pattern, {
+            result.finder.glob(prefix ? `${prefix}/${input.pattern}` : input.pattern, {
               pageIndex: 0,
               pageSize: input.limit,
             }),
@@ -197,7 +237,7 @@ export const fffLayer = Layer.effect(
           yield* SearchTarget.validate(fs, target).pipe(Effect.orDie)
           const items = yield* Effect.filter(found.value.items, (item) => safe(root, item.relativePath))
           return items.map((item) => {
-          // kilocode_change end
+            // kilocode_change end
             const absolute = path.resolve(location.directory, item.relativePath)
             return new FileSystem.Entry({
               path: RelativePath.make(item.relativePath.replaceAll("\\", "/")),
@@ -210,24 +250,26 @@ export const fffLayer = Layer.effect(
         // kilocode_change start
         Effect.gen(function* () {
           const { root, target } = yield* inspect(input.path)
-        // kilocode_change end
+          const result = yield* get
+          // kilocode_change end
           const prefix = input.path?.replaceAll("\\", "/").replace(/\/$/, "")
           // kilocode_change start
-          const found = yield* Effect.sync(() =>
-            result.value.grep(
-              [prefix ? `${prefix}/**` : undefined, input.include, input.pattern]
-                .filter((value) => value !== undefined)
-                .join(" "),
-              { mode: "regex", pageSize: input.limit, timeBudgetMs: 1_500 },
-            ),
-          // kilocode_change end
+          const found = yield* Effect.sync(
+            () =>
+              result.finder.grep(
+                [prefix ? `${prefix}/**` : undefined, input.include, input.pattern]
+                  .filter((value) => value !== undefined)
+                  .join(" "),
+                { mode: "regex", pageSize: input.limit, timeBudgetMs: 1_500 },
+              ),
+            // kilocode_change end
           )
           if (!found.ok) throw found.error
           // kilocode_change start
           yield* SearchTarget.validate(fs, target).pipe(Effect.orDie)
           const items = yield* Effect.filter(found.value.items, (item) => safe(root, item.relativePath))
           return items.map((match) => {
-          // kilocode_change end
+            // kilocode_change end
             const bytes = Buffer.from(match.lineContent)
             return new FileSystem.Match({
               entry: new FileSystem.Entry({
@@ -247,11 +289,13 @@ export const fffLayer = Layer.effect(
           })
         }),
       find: (input) =>
-        Effect.sync(() => {
+        Effect.gen(function* () {
+          // kilocode_change - load the native index only for an actual search.
+          const result = yield* get // kilocode_change
           const options = { pageIndex: 0, pageSize: input.limit ?? 50 }
           const items = (() => {
             if (input.type === "file") {
-              const found = result.value.fileSearch(input.query.trim(), options)
+              const found = result.finder.fileSearch(input.query.trim(), options)
               if (!found.ok) throw found.error
               return found.value.items.map((item, index) => ({
                 path: item.relativePath,
@@ -260,7 +304,7 @@ export const fffLayer = Layer.effect(
               }))
             }
             if (input.type === "directory") {
-              const found = result.value.directorySearch(input.query.trim(), options)
+              const found = result.finder.directorySearch(input.query.trim(), options)
               if (!found.ok) throw found.error
               return found.value.items.map((item, index) => ({
                 path: item.relativePath,
@@ -268,7 +312,7 @@ export const fffLayer = Layer.effect(
                 score: found.value.scores[index]?.total ?? 0,
               }))
             }
-            const found = result.value.mixedSearch(input.query.trim(), options)
+            const found = result.finder.mixedSearch(input.query.trim(), options)
             if (!found.ok) throw found.error
             return found.value.items.map((item, index) => ({
               path: item.item.relativePath,
diff --git a/packages/core/src/kilocode/ripgrep-grep.ts b/packages/core/src/kilocode/ripgrep-grep.ts
deleted file mode 100644
index f92cc210f99..00000000000
--- a/packages/core/src/kilocode/ripgrep-grep.ts
+++ /dev/null
@@ -1,53 +0,0 @@
-import type { Match } from "../filesystem/schema"
-
-export interface Options {
-  readonly context?: number
-  readonly literal?: boolean
-  readonly ignoreCase?: boolean
-}
-
-export type GrepMatch = Match & {
-  readonly context: boolean
-  readonly textTruncated: boolean
-}
-
-export const flags = (input: Options) => [
-  ...(input.literal ? ["--fixed-strings"] : []),
-  ...(input.ignoreCase ? ["--ignore-case"] : []),
-  ...(input.context ? [`--context=${input.context}`] : []),
-]
-
-export const stop = (limit: number) => {
-  let matches = 0
-  return (row: { readonly context: boolean }) => !row.context && ++matches > limit
-}
-
-export const select = <
-  A extends {
-    readonly context: boolean
-    readonly path: { readonly text: string }
-    readonly line_number: number
-  },
->(
-  input: { readonly limit: number; readonly context?: number },
-  items: readonly A[],
-) => {
-  let count = 0
-  const overflow = items.findIndex((row) => !row.context && ++count > input.limit)
-  const selected = items.slice(0, overflow === -1 ? items.length : overflow)
-  const matches = selected.filter((row) => !row.context)
-  return selected.filter(
-    (row) =>
-      !row.context ||
-      matches.some(
-        (match) =>
-          match.path.text === row.path.text && Math.abs(match.line_number - row.line_number) <= (input.context ?? 0),
-      ),
-  )
-}
-
-export const decorate = (match: Match, context: boolean, textTruncated: boolean): GrepMatch => ({
-  ...match,
-  context,
-  textTruncated,
-})
diff --git a/packages/core/src/ripgrep.ts b/packages/core/src/ripgrep.ts
index 5ee202a861d..e1545195606 100644
--- a/packages/core/src/ripgrep.ts
+++ b/packages/core/src/ripgrep.ts
@@ -6,7 +6,6 @@ import path from "path"
 import { LayerNode } from "./effect/layer-node"
 import { Entry, Match } from "./filesystem/schema"
 import { FSUtil } from "./fs-util"
-import * as KiloGrep from "./kilocode/ripgrep-grep" // kilocode_change
 import * as SpawnValidation from "./kilocode/spawn-validation" // kilocode_change
 import { AppProcess, collectStream, waitForAbort } from "./process"
 import { NonNegativeInt, PositiveInt, RelativePath } from "./schema"
@@ -24,7 +23,7 @@ const MAX_RECORD_BYTES = 64 * 1024
 const MAX_SUBMATCHES = 100
 
 const RawMatch = Schema.Struct({
-  type: Schema.Literals(["match", "context"]), // kilocode_change - retain requested context records
+  type: Schema.Literal("match"),
   data: Schema.Struct({
     path: Schema.Struct({ text: Schema.String }),
     lines: Schema.Struct({ text: Schema.String }),
@@ -40,7 +39,7 @@ const RawMatch = Schema.Struct({
   }),
 })
 
-type RawMatchData = (typeof RawMatch.Type)["data"] & { readonly context: boolean } // kilocode_change
+type RawMatchData = (typeof RawMatch.Type)["data"]
 
 export class Error extends Schema.TaggedErrorClass<Error>()("Ripgrep.Error", {
   message: Schema.String,
@@ -72,8 +71,7 @@ export interface GlobInput {
   readonly validate?: Effect.Effect<void, unknown> // kilocode_change - bind approved searches at spawn
 }
 
-export interface GrepInput extends KiloGrep.Options {
-  // kilocode_change
+export interface GrepInput {
   readonly cwd: string
   readonly pattern: string
   readonly file?: string
@@ -86,7 +84,7 @@ export interface GrepInput extends KiloGrep.Options {
 export interface Interface {
   readonly find: (input: FindInput) => Effect.Effect<readonly Entry[], Error>
   readonly glob: (input: GlobInput) => Effect.Effect<SearchResult<Entry>, Error> // kilocode_change
-  readonly grep: (input: GrepInput) => Effect.Effect<SearchResult<KiloGrep.GrepMatch>, Error | InvalidPatternError> // kilocode_change
+  readonly grep: (input: GrepInput) => Effect.Effect<SearchResult<Match>, Error | InvalidPatternError> // kilocode_change
 }
 
 // kilocode_change start - retain truncation state through model-facing tools
@@ -118,7 +116,6 @@ export const layer = Layer.effect(
       readonly parse: (line: string) => Effect.Effect<A | undefined, Error>
       readonly pattern?: string
       readonly onItem?: (item: A) => Effect.Effect<void>
-      readonly stop?: (item: A) => boolean // kilocode_change - stop bounded searches at the overflow match
       readonly validate?: Effect.Effect<void, unknown> // kilocode_change - spawn-bound target validation
     }) => {
       const program = Effect.scoped(
@@ -139,13 +136,6 @@ export const layer = Layer.effect(
             Effect.forkScoped,
           )
           let observed = 0
-          let stopped = false // kilocode_change
-          const take = input.stop // kilocode_change start
-            ? Stream.takeUntil<A>((row) => {
-                stopped = input.stop?.(row) ?? false
-                return stopped
-              })
-            : Stream.take(input.limit + 1) // kilocode_change end
           const rows = yield* Stream.decodeText(handle.stdout).pipe(
             Stream.splitLines,
             Stream.filter((line) => line.length > 0),
@@ -155,12 +145,11 @@ export const layer = Layer.effect(
               if (!input.onItem || observed++ >= input.limit) return Effect.void
               return input.onItem(row)
             }),
-            take, // kilocode_change
+            Stream.take(input.limit + 1),
             Stream.runCollect,
             Effect.map((chunk) => [...chunk]),
           )
-          if (stopped) return { items: rows, truncated: true, partial: false } // kilocode_change
-          const truncated = input.stop ? false : rows.length > input.limit // kilocode_change - custom stop predicates own truncation
+          const truncated = rows.length > input.limit
           if (truncated) return { items: rows.slice(0, input.limit), truncated, partial: false }
 
           const code = yield* handle.exitCode
@@ -260,13 +249,11 @@ export const layer = Layer.effect(
       grep: (input) =>
         run<RawMatchData>({
           ...input,
-          stop: KiloGrep.stop(input.limit), // kilocode_change
           args: [
             "--no-config",
             "--json",
             "--hidden",
             "--no-messages",
-            ...KiloGrep.flags(input), // kilocode_change
             ...(input.include ? [`--glob=${input.include}`] : []),
             "--glob=!**/.git/**",
             "--",
@@ -282,19 +269,13 @@ export const layer = Layer.effect(
                 })
             ).pipe(
               Effect.flatMap((json) => {
-                if (
-                  !json ||
-                  typeof json !== "object" ||
-                  !("type" in json) ||
-                  (json.type !== "match" && json.type !== "context") // kilocode_change
-                )
+                if (!json || typeof json !== "object" || !("type" in json) || json.type !== "match")
                   return Effect.succeed(undefined)
                 return Schema.decodeUnknownEffect(RawMatch)(json).pipe(
                   Effect.map((match) => ({
                     ...match.data,
                     path: { text: match.data.path.text.replace(/^\.[\\/]/, "") },
                     submatches: match.data.submatches.slice(0, MAX_SUBMATCHES),
-                    context: match.type === "context", // kilocode_change
                   })),
                   Effect.mapError((cause) => failure("Invalid ripgrep match output", cause)),
                 )
@@ -304,13 +285,13 @@ export const layer = Layer.effect(
           // kilocode_change start - retain spawn metadata after mapping matches
           Effect.map((result) => ({
             ...result,
-            items: KiloGrep.select(input, result.items).map((match) => {
+            items: result.items.map((match) => {
               const relative = match.path.text
                 .replace(/^(?:\.[\\/])+/u, "")
                 .replace(/^[\\/]+/u, "")
                 .replaceAll("\\", "/")
               const absolute = path.resolve(input.cwd, relative)
-              const item = new Match({
+              return new Match({
                 entry: new Entry({
                   path: RelativePath.make(relative),
                   type: "file",
@@ -325,7 +306,6 @@ export const layer = Layer.effect(
                   end: submatch.end,
                 })),
               })
-              return KiloGrep.decorate(item, match.context, match.lines.text.length > 2_000)
             }),
           })),
           // kilocode_change end
diff --git a/packages/core/src/v1/config/permission.ts b/packages/core/src/v1/config/permission.ts
index 36d2468bbec..6d6caa02abd 100644
--- a/packages/core/src/v1/config/permission.ts
+++ b/packages/core/src/v1/config/permission.ts
@@ -25,6 +25,7 @@ const InputObject = Schema.StructWithRest(
     bash: Schema.optional(Rule),
     task: Schema.optional(Rule),
     external_directory: Schema.optional(Rule),
+    markdown_source: Schema.optional(Rule), // kilocode_change - explicitly authorize external agent/command sources
     todowrite: Schema.optional(Action),
     question: Schema.optional(Action),
     webfetch: Schema.optional(Action),
diff --git a/packages/core/test/kilocode/fff.test.ts b/packages/core/test/kilocode/fff.test.ts
index 6be70c3dc95..686e0171bb3 100644
--- a/packages/core/test/kilocode/fff.test.ts
+++ b/packages/core/test/kilocode/fff.test.ts
@@ -1,7 +1,16 @@
 import { describe, expect, test } from "bun:test"
+import { FileFinder, type InitOptions } from "@ff-labs/fff-bun"
+import "@opencode-ai/core/filesystem"
+import { Fff } from "@opencode-ai/core/filesystem/fff.bun"
+import { FSUtil } from "@opencode-ai/core/fs-util"
 import os from "os"
 import path from "path"
+import { Context, Effect, Layer, Scope } from "effect"
 import { scanning } from "@opencode-ai/core/kilocode/fff"
+import { Location } from "@opencode-ai/core/location"
+import { AbsolutePath } from "@opencode-ai/core/schema"
+import { location } from "../fixture/location"
+import { tmpdir } from "../fixture/tmpdir"
 
 describe("FFF scanning boundaries", () => {
   test("enables filesystem-root scanning only at the exact root", () => {
@@ -25,3 +34,81 @@ describe("FFF scanning boundaries", () => {
     })
   })
 })
+
+describe("FFF lifecycle", () => {
+  test("retries a failed first search and reuses one picker", async () => {
+    if (!Fff.available()) return
+
+    const dir = await tmpdir()
+    const create = FileFinder.create
+    const calls = { create: 0, destroy: 0, opts: undefined as InitOptions | undefined }
+    try {
+      FileFinder.create = (opts) => {
+        calls.create++
+        if (calls.create === 1) return { ok: false, error: "transient failure" }
+        calls.opts = opts
+        const result = create(opts)
+        if (!result.ok) return result
+        const destroy = result.value.destroy.bind(result.value)
+        result.value.destroy = () => {
+          calls.destroy++
+          destroy()
+        }
+        return result
+      }
+
+      await Effect.runPromise(
+        Effect.acquireUseRelease(
+          Scope.make(),
+          (scope) =>
+            Effect.gen(function* () {
+              const { FileSystemSearch } = yield* Effect.promise(() => import("@opencode-ai/core/filesystem/search"))
+              const layer = FileSystemSearch.fffLayer.pipe(
+                Layer.provide(FSUtil.defaultLayer),
+                Layer.provide(
+                  Layer.succeed(
+                    Location.Service,
+                    Location.Service.of(
+                      location(
+                        { directory: AbsolutePath.make(dir.path) },
+                        { vcs: { type: "git", store: AbsolutePath.make(path.join(dir.path, ".git")) } },
+                      ),
+                    ),
+                  ),
+                ),
+              )
+              const context = yield* Layer.buildWithScope(layer, scope)
+              const service = Context.get(context, FileSystemSearch.Service)
+              expect(calls.create).toBe(0)
+
+              const first = yield* Effect.exit(
+                Effect.all(
+                  [
+                    service.find({ query: "", type: "file", limit: 1 }),
+                    service.find({ query: "", type: "file", limit: 1 }),
+                  ],
+                  { concurrency: "unbounded" },
+                ),
+              )
+              expect(first._tag).toBe("Failure")
+              expect(calls.create).toBe(1)
+
+              yield* service.find({ query: "", type: "file", limit: 1 })
+              expect(calls.create).toBe(2)
+              expect(calls.opts?.disableMmapCache).toBe(true)
+              expect(calls.opts?.disableContentIndexing).toBe(true)
+
+              yield* service.find({ query: "", type: "file", limit: 1 })
+              expect(calls.create).toBe(2)
+              expect(calls.destroy).toBe(0)
+            }),
+          (scope, exit) => Scope.close(scope, exit),
+        ),
+      )
+      expect(calls.destroy).toBe(1)
+    } finally {
+      FileFinder.create = create
+      await dir[Symbol.asyncDispose]()
+    }
+  })
+})
diff --git a/packages/core/test/pty/pty-session.test.ts b/packages/core/test/pty/pty-session.test.ts
index f74abf88a80..a238ffb579c 100644
--- a/packages/core/test/pty/pty-session.test.ts
+++ b/packages/core/test/pty/pty-session.test.ts
@@ -80,17 +80,19 @@ const attachCollecting = Effect.fn("PtySessionTest.attachCollecting")(function*
   return { attachment, output, ended }
 })
 
-const waitForOutput = (output: Queue.Queue<string>, text: string) =>
-  Effect.gen(function* () {
-    let received = ""
+const waitForOutput = (output: Queue.Queue<string>, text: string) => {
+  let received = ""
+  const pull = Effect.gen(function* () {
     while (!received.includes(text)) received += yield* Queue.take(output)
     return received
-  }).pipe(
+  })
+  return pull.pipe(
     Effect.timeoutOrElse({
       duration: PTY_TEST_TIMEOUT, // kilocode_change
-      orElse: () => Effect.fail(new Error(`timeout waiting for output containing ${JSON.stringify(text)}`)),
+      orElse: () => Effect.fail(new Error(`timeout waiting for output containing ${JSON.stringify(text)}, received ${JSON.stringify(received)}`)),
     }),
   )
+}
 
 describe("pty", () => {
   it.live("returns typed not found errors for missing sessions", () =>
@@ -143,11 +145,13 @@ describe("pty", () => {
   )
 
   // (script terminals forward raw output to xterm without transcoding).
+  // The child must outlive its output: an immediate exit can race bun-pty's
+  // reader thread and drop trailing bytes under load, so print then sleep.
   ptyTest("round-trips non-ASCII output byte-identically", () =>
     Effect.gen(function* () {
       const pty = yield* Pty.Service
       const marker = "café-über-北京-🚀"
-      const info = yield* createPty("sh", ["-c", "printf 'caf\\303\\251-\\303\\274ber-\\345\\214\\227\\344\\272\\254-\\360\\237\\232\\200\\n'"])
+      const info = yield* createPty("sh", ["-c", "printf 'caf\\303\\251-\\303\\274ber-\\345\\214\\227\\344\\272\\254-\\360\\237\\232\\200\\n'; sleep 5"])
       const attached = yield* attachCollecting(info.id)
       expect(yield* waitForOutput(attached.output, marker)).toContain(marker)
     }),
diff --git a/packages/effect-drizzle-sqlite/package.json b/packages/effect-drizzle-sqlite/package.json
index 7303d76d7ca..907db1f9a39 100644
--- a/packages/effect-drizzle-sqlite/package.json
+++ b/packages/effect-drizzle-sqlite/package.json
@@ -1,6 +1,6 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
-  "version": "7.4.18",
+  "version": "7.4.20",
   "name": "@opencode-ai/effect-drizzle-sqlite",
   "type": "module",
   "license": "MIT",
diff --git a/packages/effect-sqlite-node/package.json b/packages/effect-sqlite-node/package.json
index 2b297b5ecb3..4af05664a09 100644
--- a/packages/effect-sqlite-node/package.json
+++ b/packages/effect-sqlite-node/package.json
@@ -1,6 +1,6 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
-  "version": "7.4.18",
+  "version": "7.4.20",
   "name": "@opencode-ai/effect-sqlite-node",
   "type": "module",
   "license": "MIT",
diff --git a/packages/extensions/zed/extension.toml b/packages/extensions/zed/extension.toml
index 5321bca1b32..50fe224ed2a 100644
--- a/packages/extensions/zed/extension.toml
+++ b/packages/extensions/zed/extension.toml
@@ -1,7 +1,7 @@
 id = "kilo"
 name = "Kilo"
 description = "The open source coding agent."
-version = "7.4.18"
+version = "7.4.20"
 schema_version = 1
 authors = ["Anomaly"]
 repository = "https://github.com/Kilo-Org/kilocode"
@@ -11,26 +11,26 @@ name = "Kilo"
 icon = "./icons/opencode.svg"
 
 [agent_servers.opencode.targets.darwin-aarch64]
-archive = "https://github.com/Kilo-Org/kilocode/releases/download/v7.4.18/opencode-darwin-arm64.zip"
+archive = "https://github.com/Kilo-Org/kilocode/releases/download/v7.4.20/opencode-darwin-arm64.zip"
 cmd = "./opencode"
 args = ["acp"]
 
 [agent_servers.opencode.targets.darwin-x86_64]
-archive = "https://github.com/Kilo-Org/kilocode/releases/download/v7.4.18/opencode-darwin-x64.zip"
+archive = "https://github.com/Kilo-Org/kilocode/releases/download/v7.4.20/opencode-darwin-x64.zip"
 cmd = "./opencode"
 args = ["acp"]
 
 [agent_servers.opencode.targets.linux-aarch64]
-archive = "https://github.com/Kilo-Org/kilocode/releases/download/v7.4.18/opencode-linux-arm64.tar.gz"
+archive = "https://github.com/Kilo-Org/kilocode/releases/download/v7.4.20/opencode-linux-arm64.tar.gz"
 cmd = "./opencode"
 args = ["acp"]
 
 [agent_servers.opencode.targets.linux-x86_64]
-archive = "https://github.com/Kilo-Org/kilocode/releases/download/v7.4.18/opencode-linux-x64.tar.gz"
+archive = "https://github.com/Kilo-Org/kilocode/releases/download/v7.4.20/opencode-linux-x64.tar.gz"
 cmd = "./opencode"
 args = ["acp"]
 
 [agent_servers.opencode.targets.windows-x86_64]
-archive = "https://github.com/Kilo-Org/kilocode/releases/download/v7.4.18/opencode-windows-x64.zip"
+archive = "https://github.com/Kilo-Org/kilocode/releases/download/v7.4.20/opencode-windows-x64.zip"
 cmd = "./opencode.exe"
 args = ["acp"]
diff --git a/packages/http-recorder/package.json b/packages/http-recorder/package.json
index ff408eb4302..e931dce3e17 100644
--- a/packages/http-recorder/package.json
+++ b/packages/http-recorder/package.json
@@ -1,6 +1,6 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
-  "version": "7.4.18",
+  "version": "7.4.20",
   "name": "@opencode-ai/http-recorder",
   "description": "Record and replay Effect HTTP client traffic with deterministic cassettes",
   "type": "module",
diff --git a/packages/kilo-console/package.json b/packages/kilo-console/package.json
index c9097a403ce..2a024ace453 100755
--- a/packages/kilo-console/package.json
+++ b/packages/kilo-console/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@kilocode/kilo-console",
-  "version": "7.4.18",
+  "version": "7.4.20",
   "private": true,
   "type": "module",
   "scripts": {
diff --git a/packages/kilo-docs/LEARNINGS.md b/packages/kilo-docs/LEARNINGS.md
new file mode 100644
index 00000000000..44bb6a77430
--- /dev/null
+++ b/packages/kilo-docs/LEARNINGS.md
@@ -0,0 +1,11 @@
+# docs-sync learnings
+
+Rules the docs-sync bot learned from maintainer corrections to its rolling pull request.
+The bot reads this file at the start of every run and follows every rule below.
+
+To unlearn a rule, delete its line and commit. The next run reads this file from the
+branch, so the rule is gone from its input, and the deletion itself is a correction the
+extraction step is instructed not to undo.
+
+<!-- docs-sync:learnings:start -->
+<!-- docs-sync:learnings:end -->
diff --git a/packages/kilo-docs/package.json b/packages/kilo-docs/package.json
index 5f296eedeaf..f1c085a55f5 100644
--- a/packages/kilo-docs/package.json
+++ b/packages/kilo-docs/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@kilocode/kilo-docs",
-  "version": "7.4.18",
+  "version": "7.4.20",
   "private": true,
   "scripts": {
     "dev": "next dev --webpack --port 3002",
diff --git a/packages/kilo-docs/pages/customize/agents-md.md b/packages/kilo-docs/pages/customize/agents-md.md
index 88d231e4ec0..4f2a58235c7 100644
--- a/packages/kilo-docs/pages/customize/agents-md.md
+++ b/packages/kilo-docs/pages/customize/agents-md.md
@@ -18,7 +18,7 @@ If you'd like to migrate your memory bank content to AGENTS.md:
 
 1. Examine the contents in `.kilocode/rules/memory-bank/`
 2. Move that content into your project's `AGENTS.md` file (or ask Kilo to do it for you)
-   {% /callout %}
+{% /callout %}
 
 ## What is AGENTS.md?
 
diff --git a/packages/kilo-docs/pages/customize/custom-subagents.md b/packages/kilo-docs/pages/customize/custom-subagents.md
index 99c889db7f5..5c00ea8d77c 100644
--- a/packages/kilo-docs/pages/customize/custom-subagents.md
+++ b/packages/kilo-docs/pages/customize/custom-subagents.md
@@ -93,6 +93,20 @@ Define agents as markdown files with YAML frontmatter. Place them in:
 
 The **filename** (without `.md`) becomes the agent name.
 
+If `.kilo/agents/` is a symlink to a directory outside the project, allow that exact source in your global `~/.config/kilo/kilo.jsonc`:
+
+```jsonc
+{
+  "permission": {
+    "markdown_source": {
+      "/path/to/shared/agents/*": "allow"
+    }
+  }
+}
+```
+
+Project configuration cannot grant this permission. External agent files remain untrusted: `{env:...}` substitutions are blocked and `{file:...}` substitutions remain confined to the project.
+
 ```markdown
 ---
 description: Reviews code for quality and best practices
diff --git a/packages/kilo-docs/pages/customize/workflows.md b/packages/kilo-docs/pages/customize/workflows.md
index cb55800c87d..9d6da762ff3 100644
--- a/packages/kilo-docs/pages/customize/workflows.md
+++ b/packages/kilo-docs/pages/customize/workflows.md
@@ -17,6 +17,20 @@ Workflows are Markdown files stored as **slash commands** in `.kilo/commands/`:
 - **Global commands**: `~/.config/kilo/commands/` (available in all projects)
 - **Project commands**: `[project]/.kilo/commands/` (project-specific)
 
+If `.kilo/commands/` is a symlink to a directory outside the project, allow that exact source in your global `~/.config/kilo/kilo.jsonc`:
+
+```jsonc
+{
+  "permission": {
+    "markdown_source": {
+      "/path/to/shared/commands/*": "allow"
+    }
+  }
+}
+```
+
+Project configuration cannot grant this permission. External command files remain untrusted: `{env:...}` substitutions are blocked and `{file:...}` substitutions remain confined to the project.
+
 ### Basic Setup
 
 1. Create a `.md` file with step-by-step instructions
diff --git a/packages/kilo-docs/public/img/screenshot-tests/kilo-vscode/visual-regression/labs-tool-call-lab/search-previews-chromium-linux.png b/packages/kilo-docs/public/img/screenshot-tests/kilo-vscode/visual-regression/labs-tool-call-lab/search-previews-chromium-linux.png
index 6a4e3e8ba0b..e571fdb6845 100644
--- a/packages/kilo-docs/public/img/screenshot-tests/kilo-vscode/visual-regression/labs-tool-call-lab/search-previews-chromium-linux.png
+++ b/packages/kilo-docs/public/img/screenshot-tests/kilo-vscode/visual-regression/labs-tool-call-lab/search-previews-chromium-linux.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:fd794db4d2c038984f9e753ba70b8b0473d97a16713a9ff7255f0d2cf505d41a
-size 758306
+oid sha256:033960b68a915d0b05ce539784998d0f84603f206689dbbd14005771d112faa4
+size 762429
diff --git a/packages/kilo-gateway/package.json b/packages/kilo-gateway/package.json
index e55bbbdd5df..bb5e6796df1 100644
--- a/packages/kilo-gateway/package.json
+++ b/packages/kilo-gateway/package.json
@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@kilocode/kilo-gateway",
-  "version": "7.4.18",
+  "version": "7.4.20",
   "type": "module",
   "license": "MIT",
   "description": "Unified Kilo Gateway package for OpenCode - authentication, provider, and API integration",
diff --git a/packages/kilo-gateway/src/api/models.ts b/packages/kilo-gateway/src/api/models.ts
index d0bb964ca51..8188c1f825b 100644
--- a/packages/kilo-gateway/src/api/models.ts
+++ b/packages/kilo-gateway/src/api/models.ts
@@ -1,6 +1,7 @@
 import { z } from "zod"
 import { getKiloUrlFromToken } from "../auth/token.js"
 import { getDefaultHeaders, buildKiloHeaders } from "../headers.js"
+import { resolveKiloGatewayBaseUrl } from "./url.js"
 import { KILO_API_BASE, KILO_OPENROUTER_BASE, MODELS_FETCH_TIMEOUT_MS, PROMPTS, AI_SDK_PROVIDERS } from "./constants.js"
 
 export type KiloModelsResult = {
@@ -121,6 +122,16 @@ export type KiloImageModelsResult = {
   error?: { kind: "unauthorized" | "network" | "schema" | "http"; status?: number }
 }
 
+export type KiloTranscriptionModel = {
+  id: string
+  name: string
+}
+
+export type KiloTranscriptionModelsResult = {
+  models: KiloTranscriptionModel[]
+  error?: { kind: "unauthorized" | "network" | "schema" | "http"; status?: number }
+}
+
 /**
  * Fetch image-capable models from Kilo API (OpenRouter-compatible endpoint).
  * Uses the same raw fetch as {@link fetchKiloModels} but keeps only models
@@ -145,6 +156,52 @@ export async function fetchKiloImageModels(options?: {
   return { models }
 }
 
+export async function fetchKiloTranscriptionModels(options?: {
+  kilocodeToken?: string
+  kilocodeOrganizationId?: string
+  baseURL?: string
+}): Promise<KiloTranscriptionModelsResult> {
+  const token = options?.kilocodeToken
+  const organizationId = options?.kilocodeOrganizationId
+  const url = new URL("transcription-models", resolveKiloGatewayBaseUrl({ baseURL: options?.baseURL, token }))
+  const response = await fetch(url, {
+    headers: {
+      ...getDefaultHeaders(),
+      ...buildKiloHeaders(undefined, { kilocodeOrganizationId: organizationId }),
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    },
+    signal: AbortSignal.timeout(MODELS_FETCH_TIMEOUT_MS),
+  }).catch((err: unknown) => err as Error)
+
+  if (response instanceof Error) return { models: [], error: { kind: "network" } }
+  if (!response.ok) {
+    const kind = response.status === 401 || response.status === 403 ? "unauthorized" : "http"
+    return { models: [], error: { kind, status: response.status } }
+  }
+
+  const json = await response.json().catch(() => null)
+  if (!json || !Array.isArray(json.data)) return { models: [], error: { kind: "schema" } }
+
+  const data: unknown[] = json.data
+  const models = data.filter(isTranscriptionModel).map((model) => ({
+    id: model.id,
+    name: model.name,
+  }))
+  if (models.length === 0) return { models: [], error: { kind: "schema" } }
+  return { models }
+}
+
+type TranscriptionModelResponse = {
+  id: string
+  name: string
+}
+
+function isTranscriptionModel(value: unknown): value is TranscriptionModelResponse {
+  if (!value || typeof value !== "object") return false
+  const model = value as Record<string, unknown>
+  return typeof model.id === "string" && typeof model.name === "string"
+}
+
 /**
  * Shared raw fetch + validate used by both {@link fetchKiloModels} and {@link fetchKiloImageModels}.
  */
diff --git a/packages/kilo-gateway/src/index.ts b/packages/kilo-gateway/src/index.ts
index cee10c2f781..4df0e8a7681 100644
--- a/packages/kilo-gateway/src/index.ts
+++ b/packages/kilo-gateway/src/index.ts
@@ -41,6 +41,9 @@ export {
   fetchKiloImageModels,
   type KiloImageModel,
   type KiloImageModelsResult,
+  fetchKiloTranscriptionModels,
+  type KiloTranscriptionModel,
+  type KiloTranscriptionModelsResult,
 } from "./api/models.js"
 export {
   EMPTY_KILO_EMBEDDING_MODEL_CATALOG,
diff --git a/packages/kilo-gateway/test/api/models.test.ts b/packages/kilo-gateway/test/api/models.test.ts
index 656d27eaf05..0833ec11f30 100644
--- a/packages/kilo-gateway/test/api/models.test.ts
+++ b/packages/kilo-gateway/test/api/models.test.ts
@@ -1,7 +1,7 @@
 // Verifies fetchKiloModels typed result and 401 fallback behaviour.
 
 import { test, expect } from "bun:test"
-import { fetchKiloModels } from "../../src/api/models.js"
+import { fetchKiloModels, fetchKiloTranscriptionModels } from "../../src/api/models.js"
 
 const VALID_RESPONSE = JSON.stringify({
   data: [
@@ -330,3 +330,56 @@ test("keeps image-output models with tools and drops models without tools", asyn
   expect(result.models["test/model-a"]).toBeDefined()
   expect(result.models["test/no-tools"]).toBeUndefined()
 })
+
+test("fetches and filters the transcription catalog", async () => {
+  const orig = globalThis.fetch
+  const calls: string[] = []
+  stubFetch(async (input) => {
+    calls.push(String(input))
+    return new Response(
+      JSON.stringify({
+        data: [
+          {
+            id: "fish-audio/transcribe-1",
+            name: "Fish Audio: Transcribe 1",
+          },
+        ],
+      }),
+      { status: 200, headers: { "content-type": "application/json" } },
+    )
+  })
+
+  const result = await fetchKiloTranscriptionModels({ kilocodeToken: "token" })
+
+  ;(globalThis as any).fetch = orig
+
+  expect(result.error).toBeUndefined()
+  expect(result.models).toEqual([
+    {
+      id: "fish-audio/transcribe-1",
+      name: "Fish Audio: Transcribe 1",
+    },
+  ])
+  expect(calls[0]).toContain("/api/gateway/transcription-models")
+})
+
+test("keeps organization catalog errors from silently falling back to personal models", async () => {
+  const orig = globalThis.fetch
+  const calls: string[] = []
+  const headers: Headers[] = []
+  stubFetch(async (input, init) => {
+    calls.push(String(input))
+    headers.push(new Headers(init?.headers))
+    return new Response("Forbidden", { status: 403 })
+  })
+
+  const result = await fetchKiloTranscriptionModels({ kilocodeToken: "token", kilocodeOrganizationId: "org-1" })
+
+  ;(globalThis as any).fetch = orig
+
+  expect(result.models).toEqual([])
+  expect(result.error?.kind).toBe("unauthorized")
+  expect(calls).toHaveLength(1)
+  expect(calls[0]).toContain("/api/gateway/transcription-models")
+  expect(headers[0]?.get("X-KILOCODE-ORGANIZATIONID")).toBe("org-1")
+})
diff --git a/packages/kilo-i18n/package.json b/packages/kilo-i18n/package.json
index b74de939f7d..ec845e49b51 100644
--- a/packages/kilo-i18n/package.json
+++ b/packages/kilo-i18n/package.json
@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@kilocode/kilo-i18n",
-  "version": "7.4.18",
+  "version": "7.4.20",
   "type": "module",
   "license": "MIT",
   "description": "Kilo-specific i18n translations and overrides",
diff --git a/packages/kilo-indexing/package.json b/packages/kilo-indexing/package.json
index 7f2e39eea54..aab1178e92f 100644
--- a/packages/kilo-indexing/package.json
+++ b/packages/kilo-indexing/package.json
@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@kilocode/kilo-indexing",
-  "version": "7.4.18",
+  "version": "7.4.20",
   "type": "module",
   "license": "MIT",
   "description": "Standalone indexing engine and host helpers for Kilo Code",
diff --git a/packages/kilo-jetbrains/CHANGELOG.md b/packages/kilo-jetbrains/CHANGELOG.md
index 58f12c85b35..d000b8245ae 100644
--- a/packages/kilo-jetbrains/CHANGELOG.md
+++ b/packages/kilo-jetbrains/CHANGELOG.md
@@ -1,5 +1,15 @@
 # Changelog
 
+## 7.4.18
+
+### Patch Changes
+
+- [#12746](https://github.com/Kilo-Org/kilocode/pull/12746) [`1a506a7`](https://github.com/Kilo-Org/kilocode/commit/1a506a712c43d317a5a34b250df16845b641eff8) - Keep the JetBrains prompt send/stop button in sync when attachments are added or removed while a session is busy.
+
+- [#12746](https://github.com/Kilo-Org/kilocode/pull/12746) [`64f0373`](https://github.com/Kilo-Org/kilocode/commit/64f0373056b75546a015816dc0f18b1e380ad93f) - Fix JetBrains diff views to show compact workspace-relative file paths and keep added-file content visible in large branch diffs.
+
+- [#12746](https://github.com/Kilo-Org/kilocode/pull/12746) [`c1f6a75`](https://github.com/Kilo-Org/kilocode/commit/c1f6a75377b438edfc5c3b5dd85ebdc301302e7a) - Fix JetBrains chat transcripts rendering cropped when opening existing sessions.
+
 ## 7.5.0
 
 ### Minor Changes
@@ -150,6 +160,7 @@
 ## [7.0.12-rc.4] - 2026-08-01
 
 ### Fixed
+
 - Improve large branch diff performance by capping huge inline diff previews, compacting diff tree paths, and allowing horizontal scrolling for long file names.
 - Reflow existing long chat sessions after they load so transcripts lay out at the correct width without needing to resize the tool window.
 - Keep the prompt send/stop button synchronized when attachments are added, removed, or cleared while a session is busy.
diff --git a/packages/kilo-jetbrains/backend/build.gradle.kts b/packages/kilo-jetbrains/backend/build.gradle.kts
index 77d014030d1..e09355e19f2 100644
--- a/packages/kilo-jetbrains/backend/build.gradle.kts
+++ b/packages/kilo-jetbrains/backend/build.gradle.kts
@@ -20,9 +20,11 @@ val rawSpec = layout.buildDirectory.file("generated/openapi-spec/openapi.raw.jso
 val generatedSpec = layout.buildDirectory.file("generated/openapi-spec/openapi.json")
 val generatedProps = layout.buildDirectory.dir("generated/kilo-props")
 val generatedCli = layout.buildDirectory.dir("generated/kilo-cli-res")
+val generatedChecksums = layout.buildDirectory.dir("generated/kilo-cli-checksums")
 val pinned = providers.gradleProperty("kilo.cli.pinned").map { it.trim().toBoolean() }.orElse(true)
 val repoCli = pinned.map { !it }
 val bundled = providers.gradleProperty("kilo.cli.bundled").map { it.trim().toBoolean() }.orElse(false)
+val downloadsCli = repoCli.zip(bundled) { repo, bundle -> !repo && !bundle }
 val repoRootDir = rootProject.layout.projectDirectory.dir("../opencode")
 
 val pinnedCliVersion = providers.fileContents(rootProject.layout.projectDirectory.file("package.json")).asText.map { text ->
@@ -33,6 +35,7 @@ val pinnedCliVersion = providers.fileContents(rootProject.layout.projectDirector
 sourceSets {
     main {
         resources.srcDir(generatedProps)
+        if (downloadsCli.get()) resources.srcDir(generatedChecksums)
         if (repoCli.get() || bundled.get()) resources.srcDir(generatedCli)
         kotlin.srcDir(generatedApi)
     }
@@ -104,6 +107,16 @@ val stageBundledCli by tasks.registering(StageBundledCliTask::class) {
     archive.set(generatedCli.map { it.file("kilo-cli.zip") })
 }
 
+val writeCliChecksums by tasks.registering(WriteCliChecksumsTask::class) {
+    description = "Write pinned Kilo CLI checksums"
+    cliVersion.set(pinnedCliVersion)
+    token.set(
+        providers.environmentVariable("GH_TOKEN")
+            .orElse(providers.environmentVariable("GITHUB_TOKEN"))
+    )
+    checksums.set(generatedChecksums.map { it.file("kilo-cli-checksums.properties") })
+}
+
 val normalizeOpenApiSpec by tasks.registering(NormalizeOpenApiSpecTask::class) {
     description = "Normalize upstream CLI OpenAPI metadata before Kotlin client generation"
     dependsOn(generateOpenApiSpec)
@@ -158,6 +171,7 @@ val fixGeneratedApi by tasks.registering(FixGeneratedApiTask::class) {
 
 tasks.named("compileKotlin") {
     dependsOn(fixGeneratedApi, writeKiloProperties)
+    if (downloadsCli.get()) dependsOn(writeCliChecksums)
     if (repoCli.get()) dependsOn(stageRepoCli)
     if (bundled.get()) dependsOn(stageBundledCli)
     inputs.dir(generatedApi)
@@ -165,6 +179,7 @@ tasks.named("compileKotlin") {
 
 tasks.named("processResources") {
     dependsOn(writeKiloProperties)
+    if (downloadsCli.get()) dependsOn(writeCliChecksums)
     if (repoCli.get()) dependsOn(stageRepoCli)
     if (bundled.get()) dependsOn(stageBundledCli)
 }
diff --git a/packages/kilo-jetbrains/backend/src/main/kotlin/ai/kilocode/backend/cli/KiloCliChecksums.kt b/packages/kilo-jetbrains/backend/src/main/kotlin/ai/kilocode/backend/cli/KiloCliChecksums.kt
new file mode 100644
index 00000000000..a4c60eacf16
--- /dev/null
+++ b/packages/kilo-jetbrains/backend/src/main/kotlin/ai/kilocode/backend/cli/KiloCliChecksums.kt
@@ -0,0 +1,19 @@
+package ai.kilocode.backend.cli
+
+import java.util.Properties
+
+object KiloCliChecksums {
+    private const val RESOURCE = "kilo-cli-checksums.properties"
+
+    private val values by lazy {
+        val stream = KiloCliChecksums::class.java.classLoader.getResourceAsStream(RESOURCE)
+            ?: return@lazy emptyMap()
+        stream.use {
+            Properties().apply { load(it) }
+                .entries
+                .associate { item -> item.key.toString() to item.value.toString() }
+        }
+    }
+
+    fun load(): Map<String, String> = values
+}
diff --git a/packages/kilo-jetbrains/backend/src/main/kotlin/ai/kilocode/backend/cli/KiloCliDownloader.kt b/packages/kilo-jetbrains/backend/src/main/kotlin/ai/kilocode/backend/cli/KiloCliDownloader.kt
index 97ebcf0bcb1..bee74c12bb4 100644
--- a/packages/kilo-jetbrains/backend/src/main/kotlin/ai/kilocode/backend/cli/KiloCliDownloader.kt
+++ b/packages/kilo-jetbrains/backend/src/main/kotlin/ai/kilocode/backend/cli/KiloCliDownloader.kt
@@ -35,6 +35,7 @@ class KiloCliDownloader(
     private val root: File = File(PathManager.getSystemPath(), "kilo/cli"),
     private val baseUrl: String = "https://github.com/Kilo-Org/kilocode/releases/download",
     private val api: String = "https://api.github.com/repos/Kilo-Org/kilocode/releases/tags",
+    private val digests: Map<String, String> = KiloCliChecksums.load(),
     private val lockTimeoutMs: Long = LOCK_TIMEOUT_MS,
 ) {
     companion object {
@@ -64,7 +65,7 @@ class KiloCliDownloader(
                     cached(version, platform, exe, done)?.let { return@locked it }
                 }
 
-                val digest = asset(version, platform, ext)
+                val digest = digest(version, platform, ext)
                 val stage = stage(version, platform)
                 try {
                     val archive = File(stage, "kilo-$platform.$ext")
@@ -198,6 +199,17 @@ class KiloCliDownloader(
         throw IllegalStateException(message)
     }
 
+    private fun digest(version: String, platform: String, ext: String): String {
+        val digest = digests[platform]
+        if (digest == null) return asset(version, platform, ext)
+        if (digest.matches(DIGEST)) {
+            log.info("Using bundled Kilo CLI checksum for $version $platform")
+            return digest
+        }
+        log.warn("Ignoring malformed bundled Kilo CLI checksum for $platform: $digest")
+        return asset(version, platform, ext)
+    }
+
     private fun asset(version: String, platform: String, ext: String): String {
         val name = "kilo-$platform.$ext"
         val url = "${api.trimEnd('/')}/v$version"
diff --git a/packages/kilo-jetbrains/backend/src/main/kotlin/ai/kilocode/backend/cli/KiloCliPlatform.kt b/packages/kilo-jetbrains/backend/src/main/kotlin/ai/kilocode/backend/cli/KiloCliPlatform.kt
index 86b494da6a9..d1a38e4a6c3 100644
--- a/packages/kilo-jetbrains/backend/src/main/kotlin/ai/kilocode/backend/cli/KiloCliPlatform.kt
+++ b/packages/kilo-jetbrains/backend/src/main/kotlin/ai/kilocode/backend/cli/KiloCliPlatform.kt
@@ -4,6 +4,7 @@ import com.intellij.openapi.util.SystemInfo
 import com.intellij.util.system.CpuArch
 
 internal object KiloCliPlatform {
+    // Keep supported OS/architecture pairs in sync with Gradle CLI staging task platform lists.
     fun current(): String {
         val os = when {
             SystemInfo.isMac -> "darwin"
diff --git a/packages/kilo-jetbrains/backend/src/test/kotlin/ai/kilocode/backend/cli/KiloCliDownloaderTest.kt b/packages/kilo-jetbrains/backend/src/test/kotlin/ai/kilocode/backend/cli/KiloCliDownloaderTest.kt
index f1971c8d981..8c489813a65 100644
--- a/packages/kilo-jetbrains/backend/src/test/kotlin/ai/kilocode/backend/cli/KiloCliDownloaderTest.kt
+++ b/packages/kilo-jetbrains/backend/src/test/kotlin/ai/kilocode/backend/cli/KiloCliDownloaderTest.kt
@@ -30,8 +30,8 @@ class KiloCliDownloaderTest {
     fun `downloads extracts and caches pinned cli`() = runBlocking {
         MockWebServer().use { server ->
             val bytes = archive()
-            server.enqueue(metadata(bytes))
             server.enqueue(MockResponse().setResponseCode(200).setBody(Buffer().write(bytes)))
+            val digests = digests(bytes)
             val seen = mutableListOf<CliDownload>()
             val log = TestLog()
             val cli = KiloCliDownloader(
@@ -39,13 +39,13 @@ class KiloCliDownloaderTest {
                 root = dir,
                 baseUrl = server.url("/release").toString(),
                 api = server.url("/api").toString(),
+                digests = digests,
             ).resolve("1.2.3", onProgress = { seen.add(it) })
 
             assertTrue(cli.isFile)
             assertEquals(File(File(dir, "1.2.3"), KiloCliPlatform.current()).absolutePath, cli.parentFile.parentFile.absolutePath)
             assertEquals("#!/bin/sh\n", cli.readText())
             assertTrue(File(cli.parentFile, "kilo-sandbox-mutation-worker.js").isFile)
-            assertEquals("/api/v1.2.3", server.takeRequest().path)
             assertEquals("/release/v1.2.3/kilo-${KiloCliPlatform.current()}.${KiloCliPlatform.archive()}", server.takeRequest().path)
             assertEquals(CliDownload(0, "1.2.3", KiloCliPlatform.current()), seen.first())
             assertTrue(seen.any { it.percent == 100 && it.version == "1.2.3" && it.platform == KiloCliPlatform.current() })
@@ -65,34 +65,83 @@ class KiloCliDownloaderTest {
                 root = dir,
                 baseUrl = server.url("/release").toString(),
                 api = server.url("/api").toString(),
+                digests = digests,
             ).resolve("1.2.3", onProgress = { cachedProgress.add(it) })
             assertEquals(cli.absolutePath, cached.absolutePath)
-            assertEquals(2, server.requestCount)
+            assertEquals(1, server.requestCount)
             assertTrue(cachedProgress.isEmpty())
             assertContains(log.messages, "INFO: Using cached Kilo CLI 1.2.3 for ${KiloCliPlatform.current()} at ${cli.absolutePath}")
 
             File(cli.parentFile.parentFile, ".complete").writeText("ok\n")
-            server.enqueue(metadata(bytes))
             server.enqueue(MockResponse().setResponseCode(200).setBody(Buffer().write(bytes)))
             val stale = KiloCliDownloader(
                 log = log,
                 root = dir,
                 baseUrl = server.url("/release").toString(),
                 api = server.url("/api").toString(),
+                digests = digests,
             ).resolve("1.2.3")
             assertEquals(cli.absolutePath, stale.absolutePath)
-            assertEquals(4, server.requestCount)
+            assertEquals(2, server.requestCount)
 
-            server.enqueue(metadata(bytes))
             server.enqueue(MockResponse().setResponseCode(200).setBody(Buffer().write(bytes)))
             val forced = KiloCliDownloader(
                 log = log,
                 root = dir,
                 baseUrl = server.url("/release").toString(),
                 api = server.url("/api").toString(),
+                digests = digests,
             ).resolve("1.2.3", force = true)
             assertEquals(cli.absolutePath, forced.absolutePath)
-            assertEquals(6, server.requestCount)
+            assertEquals(3, server.requestCount)
+        }
+    }
+
+    @Test
+    fun `falls back to github metadata when bundled checksum is missing`() = runBlocking {
+        MockWebServer().use { server ->
+            val bytes = archive()
+            server.enqueue(metadata(bytes))
+            server.enqueue(MockResponse().setResponseCode(200).setBody(Buffer().write(bytes)))
+
+            val cli = KiloCliDownloader(
+                root = dir,
+                baseUrl = server.url("/release").toString(),
+                api = server.url("/api").toString(),
+                digests = mapOf("other" to "sha256:${"a".repeat(64)}"),
+            ).resolve("1.2.3")
+
+            assertTrue(cli.isFile)
+            assertEquals("/api/v1.2.3", server.takeRequest().path)
+            assertEquals("/release/v1.2.3/kilo-${KiloCliPlatform.current()}.${KiloCliPlatform.archive()}", server.takeRequest().path)
+            assertEquals(2, server.requestCount)
+        }
+    }
+
+    @Test
+    fun `falls back to github metadata when bundled checksum is malformed`() = runBlocking {
+        MockWebServer().use { server ->
+            val bytes = archive()
+            server.enqueue(metadata(bytes))
+            server.enqueue(MockResponse().setResponseCode(200).setBody(Buffer().write(bytes)))
+            val log = TestLog()
+
+            val cli = KiloCliDownloader(
+                log = log,
+                root = dir,
+                baseUrl = server.url("/release").toString(),
+                api = server.url("/api").toString(),
+                digests = mapOf(KiloCliPlatform.current() to "not-a-digest"),
+            ).resolve("1.2.3")
+
+            assertTrue(cli.isFile)
+            assertContains(
+                log.messages,
+                "WARN: Ignoring malformed bundled Kilo CLI checksum for ${KiloCliPlatform.current()}: not-a-digest"
+            )
+            assertEquals("/api/v1.2.3", server.takeRequest().path)
+            assertEquals("/release/v1.2.3/kilo-${KiloCliPlatform.current()}.${KiloCliPlatform.archive()}", server.takeRequest().path)
+            assertEquals(2, server.requestCount)
         }
     }
 
@@ -110,6 +159,7 @@ class KiloCliDownloaderTest {
                 root = dir,
                 baseUrl = server.url("/release").toString(),
                 api = server.url("/api").toString(),
+                digests = emptyMap(),
             ).resolve("1.2.3")
 
             assertTrue(cli.isFile)
@@ -132,6 +182,7 @@ class KiloCliDownloaderTest {
                 root = dir,
                 baseUrl = server.url("/release").toString(),
                 api = server.url("/api").toString(),
+                digests = emptyMap(),
             )
             val old = cli.resolve("1.2.3")
             assertEquals("#!/bin/old\n", old.readText())
@@ -158,12 +209,14 @@ class KiloCliDownloaderTest {
                 root = dir,
                 baseUrl = server.url("/release").toString(),
                 api = server.url("/api").toString(),
+                digests = emptyMap(),
             ).resolve("1.2.3")
             val ex = assertFailsWith<IllegalStateException> {
                 KiloCliDownloader(
                     root = dir,
                     baseUrl = server.url("/release").toString(),
                     api = server.url("/api").toString(),
+                    digests = emptyMap(),
                 ).resolve("1.2.3", force = true)
             }
 
@@ -186,6 +239,7 @@ class KiloCliDownloaderTest {
                     root = dir,
                     baseUrl = server.url("/release").toString(),
                     api = server.url("/api").toString(),
+                    digests = emptyMap(),
                 ).resolve("1.2.3")
             }
 
@@ -194,6 +248,28 @@ class KiloCliDownloaderTest {
         }
     }
 
+    @Test
+    fun `rejects cli archive with mismatched bundled checksum without fetching metadata`() = runBlocking {
+        MockWebServer().use { server ->
+            val bytes = archive()
+            server.enqueue(MockResponse().setResponseCode(200).setBody(Buffer().write(bytes)))
+
+            val ex = assertFailsWith<IllegalStateException> {
+                KiloCliDownloader(
+                    root = dir,
+                    baseUrl = server.url("/release").toString(),
+                    api = server.url("/api").toString(),
+                    digests = mapOf(KiloCliPlatform.current() to "sha256:${sha256("different".toByteArray())}"),
+                ).resolve("1.2.3")
+            }
+
+            assertContains(ex.message.orEmpty(), "digest mismatch")
+            assertEquals("/release/v1.2.3/kilo-${KiloCliPlatform.current()}.${KiloCliPlatform.archive()}", server.takeRequest().path)
+            assertEquals(1, server.requestCount)
+            assertFalse(File(File(File(dir, "1.2.3"), KiloCliPlatform.current()), ".complete").exists())
+        }
+    }
+
     @Test
     fun `fails clearly and logs when the release has no matching asset`() = runBlocking {
         MockWebServer().use { server ->
@@ -209,6 +285,7 @@ class KiloCliDownloaderTest {
                     root = dir,
                     baseUrl = server.url("/release").toString(),
                     api = server.url("/api").toString(),
+                    digests = emptyMap(),
                 ).resolve("1.2.3")
             }
             val name = "kilo-${KiloCliPlatform.current()}.${KiloCliPlatform.archive()}"
@@ -233,6 +310,7 @@ class KiloCliDownloaderTest {
                     root = dir,
                     baseUrl = server.url("/release").toString(),
                     api = server.url("/api").toString(),
+                    digests = emptyMap(),
                 ).resolve("1.2.3")
             }
             assertContains(ex.message.orEmpty(), "has no digest yet")
@@ -261,6 +339,7 @@ class KiloCliDownloaderTest {
                     root = dir,
                     baseUrl = server.url("/release").toString(),
                     api = server.url("/api").toString(),
+                    digests = emptyMap(),
                 ).resolve("1.2.3")
             }
 
@@ -284,6 +363,7 @@ class KiloCliDownloaderTest {
                     KiloCliDownloader(
                         log = log,
                         root = dir,
+                        digests = emptyMap(),
                         lockTimeoutMs = 50,
                     ).resolve("1.2.3")
                 }
@@ -307,6 +387,8 @@ class KiloCliDownloaderTest {
 
     private fun metadata(bytes: ByteArray) = metadata("sha256:${sha256(bytes)}")
 
+    private fun digests(bytes: ByteArray) = mapOf(KiloCliPlatform.current() to "sha256:${sha256(bytes)}")
+
     private fun metadata(digest: String) = MockResponse().setResponseCode(200).setBody(
         """{"assets":[{"name":"kilo-${KiloCliPlatform.current()}.${KiloCliPlatform.archive()}","digest":"$digest"}]}"""
     )
diff --git a/packages/kilo-jetbrains/build-tasks/src/main/kotlin/BuildTasksPlugin.kt b/packages/kilo-jetbrains/build-tasks/src/main/kotlin/BuildTasksPlugin.kt
index 1c25aaec60f..2413ce39c74 100644
--- a/packages/kilo-jetbrains/build-tasks/src/main/kotlin/BuildTasksPlugin.kt
+++ b/packages/kilo-jetbrains/build-tasks/src/main/kotlin/BuildTasksPlugin.kt
@@ -7,8 +7,8 @@ import org.gradle.api.Project
  * `id("build-tasks")` resolves in `backend/build.gradle.kts`.
  *
  * The real value lives in the custom task classes this composite build
- * provides: [NormalizeOpenApiSpecTask], [FixGeneratedApiTask], and
- * [GenerateOpenApiSpecTask].
+ * provides: [NormalizeOpenApiSpecTask], [FixGeneratedApiTask],
+ * [GenerateOpenApiSpecTask], and [WriteCliChecksumsTask].
  */
 class BuildTasksPlugin : Plugin<Project> {
     override fun apply(target: Project) {}
diff --git a/packages/kilo-jetbrains/build-tasks/src/main/kotlin/WriteCliChecksumsTask.kt b/packages/kilo-jetbrains/build-tasks/src/main/kotlin/WriteCliChecksumsTask.kt
new file mode 100644
index 00000000000..f5d6d8727a0
--- /dev/null
+++ b/packages/kilo-jetbrains/build-tasks/src/main/kotlin/WriteCliChecksumsTask.kt
@@ -0,0 +1,128 @@
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.contentOrNull
+import kotlinx.serialization.json.jsonArray
+import kotlinx.serialization.json.jsonObject
+import kotlinx.serialization.json.jsonPrimitive
+import org.gradle.api.DefaultTask
+import org.gradle.api.GradleException
+import org.gradle.api.file.RegularFileProperty
+import org.gradle.api.provider.Property
+import org.gradle.api.tasks.Input
+import org.gradle.api.tasks.Internal
+import org.gradle.api.tasks.OutputFile
+import org.gradle.api.tasks.TaskAction
+import java.net.HttpURLConnection
+import java.net.URI
+import java.time.Instant
+
+abstract class WriteCliChecksumsTask : DefaultTask() {
+    companion object {
+        private val DIGEST = Regex("^sha256:[a-f0-9]{64}$")
+        private val JSON = Json { ignoreUnknownKeys = true }
+        private const val API = "https://api.github.com/repos/Kilo-Org/kilocode/releases/tags"
+        // Keep in sync with KiloCliPlatform.current() and StageBundledCliTask.PLATFORMS.
+        private val PLATFORMS = listOf(
+            "darwin-arm64",
+            "darwin-x64",
+            "linux-arm64",
+            "linux-x64",
+            "windows-arm64",
+            "windows-x64",
+        )
+    }
+
+    @get:Input
+    abstract val cliVersion: Property<String>
+
+    @get:Internal
+    abstract val token: Property<String>
+
+    @get:OutputFile
+    abstract val checksums: RegularFileProperty
+
+    @TaskAction
+    fun run() {
+        val ver = cliVersion.get()
+        val assets = assets(ver)
+        val values = PLATFORMS.associateWith { platform ->
+            val name = "kilo-$platform.${ext(platform)}"
+            assets[name] ?: throw GradleException("Kilo CLI release $ver did not include $name")
+        }
+
+        val out = checksums.get().asFile
+        out.parentFile.mkdirs()
+        out.writeText(
+            values.entries
+                .sortedBy { it.key }
+                .joinToString(separator = "\n", postfix = "\n") { item -> "${item.key}=${item.value}" }
+        )
+    }
+
+    private fun assets(ver: String): Map<String, String> {
+        val url = "$API/v$ver"
+        logger.lifecycle("Fetching pinned Kilo CLI release checksums from $url")
+        val conn = connect(url)
+        try {
+            val code = conn.responseCode
+            if (code !in 200..299) fail(conn, code, "Failed to fetch pinned Kilo CLI release checksums")
+            val body = conn.inputStream.bufferedReader().use { it.readText() }
+            return JSON.parseToJsonElement(body).jsonObject["assets"]?.jsonArray
+                ?.associate { item ->
+                    val obj = item.jsonObject
+                    val name = obj["name"]?.jsonPrimitive?.contentOrNull
+                    val digest = obj["digest"]?.jsonPrimitive?.contentOrNull
+                    if (name.isNullOrBlank() || digest.isNullOrBlank()) return@associate "" to ""
+                    name to digest
+                }
+                ?.filter { it.key.isNotEmpty() }
+                ?.mapValues { item ->
+                    val digest = item.value
+                    if (!digest.matches(DIGEST)) {
+                        throw GradleException("Pinned Kilo CLI release $ver asset ${item.key} has invalid digest")
+                    }
+                    digest
+                }
+                ?: emptyMap()
+        } finally {
+            conn.disconnect()
+        }
+    }
+
+    private fun connect(url: String): HttpURLConnection {
+        val conn = URI(url).toURL().openConnection() as HttpURLConnection
+        conn.connectTimeout = 30_000
+        conn.readTimeout = 120_000
+        conn.instanceFollowRedirects = true
+        conn.setRequestProperty("Accept", "application/vnd.github+json")
+        token.getOrNull()
+            ?.trim()
+            ?.takeIf { it.isNotEmpty() }
+            ?.let { conn.setRequestProperty("Authorization", "Bearer $it") }
+        return conn
+    }
+
+    private fun fail(conn: HttpURLConnection, code: Int, msg: String): Nothing {
+        val info = rate(conn)
+        val body = runCatching { conn.errorStream?.bufferedReader()?.use { it.readText() } }
+            .getOrNull()
+            ?.take(500)
+        val detail = if (body.isNullOrBlank()) "" else ": $body"
+        if (limited(conn, code)) {
+            throw GradleException("GitHub API rate limit exceeded while fetching Kilo CLI checksums ($info)$detail")
+        }
+        throw GradleException("$msg: HTTP $code from ${conn.url} ($info)$detail")
+    }
+
+    private fun rate(conn: HttpURLConnection): String {
+        val reset = conn.getHeaderField("X-RateLimit-Reset")
+            ?.toLongOrNull()
+            ?.let { Instant.ofEpochSecond(it).toString() }
+        return "limit=${conn.getHeaderField("X-RateLimit-Limit")} remaining=${conn.getHeaderField("X-RateLimit-Remaining")} " +
+            "used=${conn.getHeaderField("X-RateLimit-Used")} reset=$reset retryAfter=${conn.getHeaderField("Retry-After")}"
+    }
+
+    private fun limited(conn: HttpURLConnection, code: Int) =
+        code == 429 || (code == 403 && conn.getHeaderField("X-RateLimit-Remaining") == "0")
+
+    private fun ext(platform: String) = if (platform.startsWith("linux-")) "tar.gz" else "zip"
+}
diff --git a/packages/kilo-jetbrains/frontend/src/main/kotlin/ai/kilocode/client/session/model/PromptAttachment.kt b/packages/kilo-jetbrains/frontend/src/main/kotlin/ai/kilocode/client/session/model/PromptAttachment.kt
index ffb642a7e96..214df0ab6a4 100644
--- a/packages/kilo-jetbrains/frontend/src/main/kotlin/ai/kilocode/client/session/model/PromptAttachment.kt
+++ b/packages/kilo-jetbrains/frontend/src/main/kotlin/ai/kilocode/client/session/model/PromptAttachment.kt
@@ -18,35 +18,55 @@ data class PromptAttachment(
     val mime: String,
     val url: String,
     val path: Path? = null,
+    val reference: Boolean = false,
 ) {
-    fun part() = PromptPartDto(
-        type = "file",
-        mime = mime,
-        url = path?.let { data(it, mime) } ?: url,
-        filename = name,
-    )
+    fun part(): PromptPartDto {
+        if (reference) {
+            return PromptPartDto(
+                type = "file",
+                mime = mime,
+                url = url,
+                filename = name,
+            )
+        }
+        return PromptPartDto(
+            type = "file",
+            mime = mime,
+            url = path?.let { data(it, mime) } ?: url,
+            filename = name,
+        )
+    }
 }
 
 object PromptAttachmentExtractor {
     private const val MAX_BYTES = 10 * 1024 * 1024
 
     fun files(files: List<java.io.File>): List<PromptAttachment> = files
-        .filter { it.exists() && it.isFile && it.canRead() && it.length() <= MAX_BYTES }
-        .map { file ->
+        .filter { it.exists() && it.canRead() }
+        .mapNotNull { file ->
             val path = file.toPath()
             val mime = mime(file)
-            if (!media(mime)) return@map null
-            PromptAttachment(
+            if (image(mime)) {
+                if (!file.isFile || file.length() > MAX_BYTES) return@mapNotNull null
+                return@mapNotNull PromptAttachment(
+                    id = path.toAbsolutePath().normalize().toString(),
+                    name = path.fileName?.toString() ?: path.name,
+                    mime = mime,
+                    url = path.toUri().toString(),
+                    path = path,
+                )
+            }
+            return@mapNotNull PromptAttachment(
                 id = path.toAbsolutePath().normalize().toString(),
                 name = path.fileName?.toString() ?: path.name,
-                mime = mime,
+                mime = if (file.isDirectory) mime else "text/plain",
                 url = path.toUri().toString(),
                 path = path,
+                reference = true,
             )
         }
-        .filterNotNull()
 
-    fun media(mime: String): Boolean = mime.startsWith("image/") || mime == "text/plain"
+    fun image(mime: String): Boolean = mime.startsWith("image/")
 
     fun image(raw: Any): PromptAttachment? {
         val image = when (raw) {
diff --git a/packages/kilo-jetbrains/frontend/src/main/kotlin/ai/kilocode/client/session/ui/prompt/PromptPanel.kt b/packages/kilo-jetbrains/frontend/src/main/kotlin/ai/kilocode/client/session/ui/prompt/PromptPanel.kt
index ba7c2a03530..dbea7374493 100644
--- a/packages/kilo-jetbrains/frontend/src/main/kotlin/ai/kilocode/client/session/ui/prompt/PromptPanel.kt
+++ b/packages/kilo-jetbrains/frontend/src/main/kotlin/ai/kilocode/client/session/ui/prompt/PromptPanel.kt
@@ -726,7 +726,7 @@ class PromptPanel(
 
     @RequiresEdt
     private fun addAttachment(item: PromptAttachment) {
-        if (!attachment && PromptAttachmentExtractor.media(item.mime)) {
+        if (!attachment && !item.reference && PromptAttachmentExtractor.image(item.mime)) {
             LOG.debug { "kind=prompt-attachment add name=${item.name} mime=${item.mime} blocked=unsupported-model" }
             notify(KiloBundle.message("prompt.attachment.unsupported.model"))
             return
@@ -813,7 +813,15 @@ class PromptPanel(
                 val items = PromptAttachmentExtractor.files(list) + listOfNotNull(image)
                 val ms = elapsedMs(start)
                 LOG.debug { "kind=$kind extract area=$area files=${list.size} image=${image != null} attachments=${items.size} extractMs=$ms sourceMs=$sourceMs" }
-                if (items.isEmpty()) return@executeOnPooledThread
+                if (items.isEmpty()) {
+                    if (list.isNotEmpty()) {
+                        ApplicationManager.getApplication().invokeLater {
+                            if (project.isDisposed) return@invokeLater
+                            notify(KiloBundle.message("prompt.attachment.drop.empty"))
+                        }
+                    }
+                    return@executeOnPooledThread
+                }
                 ApplicationManager.getApplication().invokeLater {
                     if (project.isDisposed) return@invokeLater
                     LOG.debug { "kind=$kind attach area=$area files=${list.size} image=${image != null} attachments=${items.size} extractMs=$ms sourceMs=$sourceMs" }
@@ -827,7 +835,9 @@ class PromptPanel(
 
     private fun dropFiles(event: DnDEvent): List<java.io.File> {
         if (!FileCopyPasteUtil.isFileListFlavorAvailable(event)) return emptyList()
-        return FileCopyPasteUtil.getFileListFromAttachedObject(event.attachedObject).orEmpty()
+        val files = FileCopyPasteUtil.getFileListFromAttachedObject(event.attachedObject)
+        if (files.isNotEmpty()) return files
+        return FileCopyPasteUtil.getFileList(event).orEmpty()
     }
 
     private fun elapsedMs(start: Long) = (System.nanoTime() - start) / 1_000_000
diff --git a/packages/kilo-jetbrains/frontend/src/main/resources/messages/KiloBundle.properties b/packages/kilo-jetbrains/frontend/src/main/resources/messages/KiloBundle.properties
index 838d66d0ecd..0140ed4d7bf 100644
--- a/packages/kilo-jetbrains/frontend/src/main/resources/messages/KiloBundle.properties
+++ b/packages/kilo-jetbrains/frontend/src/main/resources/messages/KiloBundle.properties
@@ -217,7 +217,8 @@ prompt.attachment.remove=Remove {0}
 prompt.attachment.open=Open {0}
 prompt.attachment.tooltip=Name: {0}\nType: {1}\nLocation: {2}
 prompt.attachment.embedded=Embedded content
-prompt.attachment.unsupported.model=The selected model does not support image or PDF attachments.
+prompt.attachment.unsupported.model=The selected model does not support image attachments.
+prompt.attachment.drop.empty=No files could be added.
 prompt.attachment.missing=Attachment no longer exists: {0}
 prompt.attachment.send.failed=Failed to send attachment: {0}
 session.attachment.title=Attachment
diff --git a/packages/kilo-jetbrains/frontend/src/test/kotlin/ai/kilocode/client/session/model/PromptAttachmentExtractorTest.kt b/packages/kilo-jetbrains/frontend/src/test/kotlin/ai/kilocode/client/session/model/PromptAttachmentExtractorTest.kt
new file mode 100644
index 00000000000..8b476859313
--- /dev/null
+++ b/packages/kilo-jetbrains/frontend/src/test/kotlin/ai/kilocode/client/session/model/PromptAttachmentExtractorTest.kt
@@ -0,0 +1,83 @@
+package ai.kilocode.client.session.model
+
+import junit.framework.TestCase
+import java.io.File
+import kotlin.io.path.createTempDirectory
+
+class PromptAttachmentExtractorTest : TestCase() {
+
+    fun `test code file becomes reference attachment`() {
+        val file = File.createTempFile("kilo-drop", ".php")
+        file.writeText("<?php echo 'hello';")
+
+        val item = PromptAttachmentExtractor.files(listOf(file)).single()
+        val part = item.part()
+
+        assertTrue(item.reference)
+        assertEquals("text/plain", item.mime)
+        assertEquals(file.toPath().toUri().toString(), item.url)
+        assertEquals(file.toPath(), item.path)
+        assertEquals(file.name, item.name)
+        assertEquals("file", part.type)
+        assertEquals("text/plain", part.mime)
+        assertEquals(file.toPath().toUri().toString(), part.url)
+        assertFalse(part.url.orEmpty().startsWith("data:"))
+    }
+
+    fun `test text file becomes reference attachment`() {
+        val file = File.createTempFile("kilo-drop", ".txt")
+        file.writeText("hello")
+
+        val item = PromptAttachmentExtractor.files(listOf(file)).single()
+
+        assertTrue(item.reference)
+        assertEquals("text/plain", item.mime)
+        assertEquals(file.toPath().toUri().toString(), item.part().url)
+    }
+
+    fun `test directory becomes reference attachment`() {
+        val dir = createTempDirectory(prefix = "kilo-drop").toFile()
+
+        val item = PromptAttachmentExtractor.files(listOf(dir)).single()
+        val part = item.part()
+
+        assertTrue(item.reference)
+        assertEquals("application/x-directory", item.mime)
+        assertEquals(dir.toPath().toUri().toString(), item.url)
+        assertEquals(dir.toPath(), item.path)
+        assertEquals(dir.name, item.name)
+        assertEquals("file", part.type)
+        assertEquals("application/x-directory", part.mime)
+        assertEquals(dir.toPath().toUri().toString(), part.url)
+    }
+
+    fun `test image file remains embedded attachment`() {
+        val file = File.createTempFile("kilo-drop", ".png")
+        file.writeBytes(byteArrayOf(1, 2, 3))
+
+        val item = PromptAttachmentExtractor.files(listOf(file)).single()
+
+        assertFalse(item.reference)
+        assertEquals("image/png", item.mime)
+        assertEquals(file.toPath().toUri().toString(), item.url)
+        assertTrue(item.part().url.orEmpty().startsWith("data:image/png;base64,"))
+    }
+
+    fun `test oversized image is skipped but oversized code is referenced`() {
+        val image = File.createTempFile("kilo-drop", ".png")
+        image.writeBytes(ByteArray(10 * 1024 * 1024 + 1))
+        val code = File.createTempFile("kilo-drop", ".php")
+        code.writeBytes(ByteArray(10 * 1024 * 1024 + 1))
+
+        val items = PromptAttachmentExtractor.files(listOf(image, code))
+
+        assertEquals(listOf(code.name), items.map { it.name })
+        assertTrue(items.single().reference)
+    }
+
+    fun `test nonexistent file is ignored`() {
+        val file = File(File(System.getProperty("java.io.tmpdir")), "kilo-missing-${System.nanoTime()}.php")
+
+        assertTrue(PromptAttachmentExtractor.files(listOf(file)).isEmpty())
+    }
+}
diff --git a/packages/kilo-jetbrains/frontend/src/test/kotlin/ai/kilocode/client/session/ui/PromptPanelTest.kt b/packages/kilo-jetbrains/frontend/src/test/kotlin/ai/kilocode/client/session/ui/PromptPanelTest.kt
index 5d9ecab3331..cb787b2b77d 100644
--- a/packages/kilo-jetbrains/frontend/src/test/kotlin/ai/kilocode/client/session/ui/PromptPanelTest.kt
+++ b/packages/kilo-jetbrains/frontend/src/test/kotlin/ai/kilocode/client/session/ui/PromptPanelTest.kt
@@ -966,17 +966,18 @@ class PromptPanelTest : BasePlatformTestCase() {
         assertEquals(1, panel.attachmentCountForTest())
     }
 
-    fun `test frontend file attachment defers data url encoding until send`() {
+    fun `test frontend text file attachment stays file reference`() {
         val file = File.createTempFile("kilo-paste", ".txt")
         file.writeText("hello")
 
         val item = ai.kilocode.client.session.model.PromptAttachmentExtractor.files(listOf(file)).single()
 
+        assertTrue(item.reference)
         assertTrue(item.url.startsWith("file://"))
-        assertTrue(item.part().url.orEmpty().startsWith("data:text/plain;base64,"))
+        assertEquals(item.url, item.part().url)
     }
 
-    fun `test pasted frontend file sends data url payload`() {
+    fun `test pasted frontend file sends reference payload`() {
         var sent: ai.kilocode.rpc.dto.PromptPartDto? = null
         val panel = PromptPanel(project, { _, files -> sent = files.single() }, {}, { _, _ -> })
         val file = File.createTempFile("kilo-paste", ".txt")
@@ -990,8 +991,7 @@ class PromptPanelTest : BasePlatformTestCase() {
 
         val item = sent!!
         assertEquals("text/plain", item.mime)
-        assertTrue(item.url.orEmpty().startsWith("data:text/plain;base64,"))
-        assertFalse(item.url.orEmpty().startsWith("file://"))
+        assertEquals(file.toPath().toUri().toString(), item.url)
     }
 
     fun `test raw image paste adds attachment`() {
@@ -1038,6 +1038,18 @@ class PromptPanelTest : BasePlatformTestCase() {
         assertEquals(0, panel.attachmentCountForTest())
     }
 
+    fun `test disabled media model allows file reference attachment`() {
+        val panel = PromptPanel(project, { _, _ -> }, {}, { _, _ -> })
+        val file = File.createTempFile("kilo-paste", ".php")
+        file.writeText("<?php echo 'hello';")
+        val item = ai.kilocode.client.session.model.PromptAttachmentExtractor.files(listOf(file)).single()
+        panel.setAttachmentEnabled(false)
+
+        panel.addAttachmentForTest(item)
+
+        assertEquals(1, panel.attachmentCountForTest())
+    }
+
     fun `test prompt button switches between send and stop state`() {
         val panel = PromptPanel(project = project, onSend = { _, _ -> }, onAbort = {}, onEnhance = { _, _ -> })
 
diff --git a/packages/kilo-jetbrains/package.json b/packages/kilo-jetbrains/package.json
index 57a8e11ef2d..e5637fdf3df 100644
--- a/packages/kilo-jetbrains/package.json
+++ b/packages/kilo-jetbrains/package.json
@@ -8,7 +8,7 @@
     "test": "./gradlew test",
     "test:ci": "bun script/test-ci.ts"
   },
-  "version": "7.4.17",
+  "version": "7.4.20",
   "dependencies": {},
   "devDependencies": {},
   "peerDependencies": {}
diff --git a/packages/kilo-memory/package.json b/packages/kilo-memory/package.json
index 4989cfc0f2c..24b2e775f62 100644
--- a/packages/kilo-memory/package.json
+++ b/packages/kilo-memory/package.json
@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@kilocode/kilo-memory",
-  "version": "7.4.18",
+  "version": "7.4.20",
   "type": "module",
   "license": "MIT",
   "description": "Project memory storage, indexing, recall, and command helpers for Kilo Code",
diff --git a/packages/kilo-sandbox/package.json b/packages/kilo-sandbox/package.json
index 1355fc2e076..0f992f992ab 100644
--- a/packages/kilo-sandbox/package.json
+++ b/packages/kilo-sandbox/package.json
@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@kilocode/sandbox",
-  "version": "7.4.18",
+  "version": "7.4.20",
   "type": "module",
   "license": "MIT",
   "private": true,
diff --git a/packages/kilo-telemetry/package.json b/packages/kilo-telemetry/package.json
index 63a01315655..4ce691dbb55 100644
--- a/packages/kilo-telemetry/package.json
+++ b/packages/kilo-telemetry/package.json
@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@kilocode/kilo-telemetry",
-  "version": "7.4.18",
+  "version": "7.4.20",
   "type": "module",
   "license": "MIT",
   "description": "Telemetry for Kilo CLI - PostHog analytics integration",
diff --git a/packages/kilo-telemetry/src/__tests__/telemetry.test.ts b/packages/kilo-telemetry/src/__tests__/telemetry.test.ts
index 939bb5dd243..c86a249f51f 100644
--- a/packages/kilo-telemetry/src/__tests__/telemetry.test.ts
+++ b/packages/kilo-telemetry/src/__tests__/telemetry.test.ts
@@ -85,6 +85,19 @@ describe("TelemetryEvent", () => {
 })
 
 describe("Telemetry", () => {
+  test("skips identity updates when disabled", async () => {
+    const enabled = spyOn(Client, "isEnabled").mockReturnValue(false)
+    const update = spyOn(Identity, "updateFromKiloAuth").mockResolvedValue()
+
+    try {
+      await Telemetry.updateIdentity("token")
+      expect(update).not.toHaveBeenCalled()
+    } finally {
+      enabled.mockRestore()
+      update.mockRestore()
+    }
+  })
+
   test("includes host OS properties", () => {
     const capture = spyOn(Client, "capture").mockImplementation(() => {})
 
diff --git a/packages/kilo-telemetry/src/telemetry.ts b/packages/kilo-telemetry/src/telemetry.ts
index 496bf1ad4c9..9e819e25519 100644
--- a/packages/kilo-telemetry/src/telemetry.ts
+++ b/packages/kilo-telemetry/src/telemetry.ts
@@ -105,6 +105,8 @@ export namespace Telemetry {
   }
 
   export async function updateIdentity(token: string | null, accountId?: string): Promise<void> {
+    if (!isEnabled()) return
+
     const previousId = Identity.getDistinctId()
     await Identity.updateFromKiloAuth(token, accountId)
 
diff --git a/packages/kilo-ui/package.json b/packages/kilo-ui/package.json
index 8724dc548f9..6948cbadbac 100644
--- a/packages/kilo-ui/package.json
+++ b/packages/kilo-ui/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@kilocode/kilo-ui",
-  "version": "7.4.18",
+  "version": "7.4.20",
   "type": "module",
   "license": "MIT",
   "exports": {
diff --git a/packages/kilo-ui/src/components/message-part.tsx b/packages/kilo-ui/src/components/message-part.tsx
index 0a61e75f6c6..4281174d125 100644
--- a/packages/kilo-ui/src/components/message-part.tsx
+++ b/packages/kilo-ui/src/components/message-part.tsx
@@ -2799,18 +2799,9 @@ ToolRegistry.register({
                 >
                   <For each={files()}>
                     {(file) => {
-                      const active = createMemo(() => expanded().includes(file.filePath))
-                      const [visible, setVisible] = createSignal(false)
-                      createEffect(() => {
-                        if (!active()) {
-                          setVisible(false)
-                          return
-                        }
-                        requestAnimationFrame(() => {
-                          if (!active()) return
-                          setVisible(true)
-                        })
-                      })
+                      // Diff defers its own expensive render; mounting the container
+                      // here avoids dropping the last item during batch expansion.
+                      const active = createMemo(() => allExpanded().includes(file.filePath))
 
                       return (
                         <Accordion.Item value={file.filePath} data-type={file.type}>
@@ -2864,7 +2855,7 @@ ToolRegistry.register({
                             </Accordion.Trigger>
                           </StickyAccordionHeader>
                           <Accordion.Content>
-                            <Show when={visible() && view(file)}>
+                            <Show when={active() && view(file)}>
                               {(diff) => (
                                 <div data-component="apply-patch-file-diff">
                                   <Dynamic
diff --git a/packages/kilo-vscode/CHANGELOG.md b/packages/kilo-vscode/CHANGELOG.md
index 5a7cdeac28a..2a67fd8e945 100644
--- a/packages/kilo-vscode/CHANGELOG.md
+++ b/packages/kilo-vscode/CHANGELOG.md
@@ -1,5 +1,51 @@
 # kilo-code
 
+## 7.4.20
+
+### Patch Changes
+
+- [#12841](https://github.com/Kilo-Org/kilocode/pull/12841) [`744c5c4`](https://github.com/Kilo-Org/kilocode/commit/744c5c4a6b244d2aac38b7acc08f98a4086544ad) - Discover available speech-to-text models from the Kilo Gateway while retaining offline fallback support and organization model restrictions.
+
+- [#12842](https://github.com/Kilo-Org/kilocode/pull/12842) [`2613ff9`](https://github.com/Kilo-Org/kilocode/commit/2613ff93c6446eb3a662ed6d4a4b063131a6a371) - Show the first Agent Manager terminal prompt sooner by deferring optional terminal enhancements until after initial paint.
+
+- [#12839](https://github.com/Kilo-Org/kilocode/pull/12839) [`4af1d1c`](https://github.com/Kilo-Org/kilocode/commit/4af1d1c8abd15881f5c06554cca8e2f6133003ee) - Keep the final file visible when expanding multi-file patch results.
+
+## 7.4.19
+
+### Minor Changes
+
+- [#12729](https://github.com/Kilo-Org/kilocode/pull/12729) [`ce7984f`](https://github.com/Kilo-Org/kilocode/commit/ce7984fc4247fb2805990ef62e1b1d9f286de9d9) - Configure a model and reasoning variant for each workflow from Agent Behaviour settings.
+
+### Patch Changes
+
+- [#12796](https://github.com/Kilo-Org/kilocode/pull/12796) [`20d1648`](https://github.com/Kilo-Org/kilocode/commit/20d1648e7a10f981fde09fc4d5e9de5c89b1dda8) - Fix Agent Manager mode shortcuts in the New Worktree dialog so the selected mode and its matching model stay in sync.
+
+- [#12725](https://github.com/Kilo-Org/kilocode/pull/12725) [`f239f36`](https://github.com/Kilo-Org/kilocode/commit/f239f36f65a1edb5ef89748933b49b3f21639a45) - Show aggregate added and removed line counts for multi-file patch tool calls.
+
+- [#12803](https://github.com/Kilo-Org/kilocode/pull/12803) [`9819c1c`](https://github.com/Kilo-Org/kilocode/commit/9819c1c315bd05631862ad6f21bbef21d73b7bdc) - Restore Agent Manager sections and worktree drag-and-drop when multiple projects are shown, with ordering and section moves scoped to the owning project.
+
+- [#12836](https://github.com/Kilo-Org/kilocode/pull/12836) [`4f7dfe6`](https://github.com/Kilo-Org/kilocode/commit/4f7dfe65cc85ef7d103a9d0d93f86b030f7142e0) - Remove the duplicate border along the Kilo Code sidebar edge.
+
+- [#12814](https://github.com/Kilo-Org/kilocode/pull/12814) [`cd7d053`](https://github.com/Kilo-Org/kilocode/commit/cd7d053f03fa7b5434b6fcae9e2c68e415b54331) - Start voice input faster on macOS with native AVFoundation capture.
+
+- [#12795](https://github.com/Kilo-Org/kilocode/pull/12795) [`37559f8`](https://github.com/Kilo-Org/kilocode/commit/37559f8643ef8ecb68ee04eae770c9b47feee88a) - Restore keyboard focus to the prompt or pending question when switching Agent Manager worktrees and sessions.
+
+- [#12799](https://github.com/Kilo-Org/kilocode/pull/12799) [`7cfaeb2`](https://github.com/Kilo-Org/kilocode/commit/7cfaeb2c8dbe7355b1d92d9a8f62d6bdfb7f6d46) - Show and hide Agent Manager worktree hover cards instantly.
+
+- [#12805](https://github.com/Kilo-Org/kilocode/pull/12805) [`8490124`](https://github.com/Kilo-Org/kilocode/commit/84901241c0c6dcb735d7e229bd9bce2c0f7e5c36) - Keep the prompt controls at a consistent height when the model selector shows the prompt-training indicator.
+
+- [#12810](https://github.com/Kilo-Org/kilocode/pull/12810) [`e04f653`](https://github.com/Kilo-Org/kilocode/commit/e04f6531bf3ef2eed5cde6e1d81a4983f276b9ca) - Update model search results instantly and keep the active match visible while typing.
+
+- [#12815](https://github.com/Kilo-Org/kilocode/pull/12815) [`3d4294e`](https://github.com/Kilo-Org/kilocode/commit/3d4294e3bb50630159233c8063b253dc5f3da8d3) - Allow Agent Manager sessions to move their worktree between sections or ungroup it through the `agent_manager` tool.
+
+- [#12798](https://github.com/Kilo-Org/kilocode/pull/12798) [`dfc1607`](https://github.com/Kilo-Org/kilocode/commit/dfc16076934decb6578730ea41f9705e2acc0923) - Bind voice input to Cmd/Ctrl+K in Kilo prompt and review comment fields, with hold-to-talk and release-to-send support.
+
+- [#12801](https://github.com/Kilo-Org/kilocode/pull/12801) [`4810766`](https://github.com/Kilo-Org/kilocode/commit/4810766d058f53084b8a6cb0fe4d1ff42973e89b) - Preserve prompt or Agent Manager terminal focus independently for each session when switching sessions.
+
+- [#12812](https://github.com/Kilo-Org/kilocode/pull/12812) [`6ae16f9`](https://github.com/Kilo-Org/kilocode/commit/6ae16f9d6272b3bfba998bb516cba7667935d6e4) - Start a fresh shell in the same Agent Manager terminal tab when the user types after the terminal ends.
+
+- [#12733](https://github.com/Kilo-Org/kilocode/pull/12733) [`63220e0`](https://github.com/Kilo-Org/kilocode/commit/63220e019c048d6df639a4b2fbd4c5c3f124547f) Thanks [@rakshith1928](https://github.com/rakshith1928)! - Fix skill folder path and URL rows clipping and pushing the remove (×) button off-screen in narrow Skills settings panels. Long paths and URLs now truncate within their row, and hovering a truncated value shows the full path or URL in a tooltip.
+
 ## 7.4.18
 
 ### Minor Changes
diff --git a/packages/kilo-vscode/package.json b/packages/kilo-vscode/package.json
index 71e266cd363..26d6af3ffad 100644
--- a/packages/kilo-vscode/package.json
+++ b/packages/kilo-vscode/package.json
@@ -2,7 +2,7 @@
   "name": "kilo-code",
   "displayName": "Kilo Code: AI Coding Agent, Copilot, and Autocomplete",
   "description": "Open Source AI coding agent that generates code from natural language, automates tasks, and runs terminal commands. Features inline autocomplete, browser automation, automated refactoring, and custom modes for planning, coding, and debugging. Supports 500+ AI models including Claude (Anthropic), Gemini, Grok, GPT, Codex and GLM.",
-  "version": "7.4.18",
+  "version": "7.4.20",
   "icon": "assets/icons/logo-outline-black.png",
   "galleryBanner": {
     "color": "#FFFFFF",
diff --git a/packages/kilo-vscode/src/KiloProvider.ts b/packages/kilo-vscode/src/KiloProvider.ts
index 980f8e42722..c04d818b4b8 100644
--- a/packages/kilo-vscode/src/KiloProvider.ts
+++ b/packages/kilo-vscode/src/KiloProvider.ts
@@ -50,7 +50,6 @@ import {
 import { GitOps } from "./agent-manager/GitOps"
 import { GitStatsPoller, type LocalStats } from "./agent-manager/GitStatsPoller"
 import { diffSummary as localDiffSummary } from "./agent-manager/local-diff"
-import { getWorkspaceRoot } from "./review-utils"
 import { createMarketplaceRemover, removeMcp } from "./kilo-provider/remove-config-item"
 import { AgentRequirementsController } from "./kilo-provider/agent-requirements-controller"
 import type { RemoteStatusService } from "./services/RemoteStatusService"
@@ -169,6 +168,8 @@ import type { ProjectRef, SessionRef, WorktreeRef } from "./agent-manager/projec
 import { indexingConsentStore, registeredProjects } from "./indexing-consent"
 import { fetchKiloEmbeddingModelCatalog } from "@kilocode/kilo-gateway"
 import { fetchImageModels } from "./image-generation/models"
+import { fetchSpeechToTextModels } from "./speech-to-text/catalog"
+import { SPEECH_TO_TEXT_MODELS } from "./speech-to-text/models"
 import { stopSessionProcesses } from "./kilo-provider/background-process"
 import { sandboxDefault, sandboxSessionMetadata } from "./shared/sandbox-session"
 import {
@@ -439,6 +440,8 @@ export class KiloProvider implements vscode.WebviewViewProvider, TelemetryProper
   private statsGitOps: GitOps | null = null
   private cachedStats: unknown = null
   private cachedGitRepo = false
+  private cachedGitDirectory: string | undefined
+  private gitStatusRevision = 0
 
   private onBeforeMessage: ((msg: Record<string, unknown>) => Promise<Record<string, unknown> | null>) | null = null
 
@@ -1021,6 +1024,7 @@ export class KiloProvider implements vscode.WebviewViewProvider, TelemetryProper
           exportTranscript: (sessionID) => this.handleExportSessionTranscript(sessionID),
           copy: (text) => vscode.env.clipboard.writeText(text),
           openSessions: (ids) => this.trackOpenSessions(ids),
+          speechToTextModels: () => this.fetchAndSendSpeechToTextModels(),
         })
       ) {
         return
@@ -1661,6 +1665,8 @@ export class KiloProvider implements vscode.WebviewViewProvider, TelemetryProper
       // Subscribe to SSE events for this webview (filtered by tracked sessions)
       this.unsubscribeEvent = this.connectionService.onEventFiltered(
         (payload, directory) => {
+          if (directory && !this.isCurrentProjectDirectory(directory)) return false
+          if (!directory && isEventFromForeignProject(payload, this.projectID)) return false
           const event = unwrapSyncEvent(payload)
           if (!event) return false
 
@@ -1672,6 +1678,7 @@ export class KiloProvider implements vscode.WebviewViewProvider, TelemetryProper
 
           // message.part.* events are always session-scoped; drop if session unknown.
           if (!sessionId) return !isSessionScopedPartEvent(event.type)
+          if (!directory && !this.isCurrentProjectSession(sessionId)) return false
 
           if (event.type === "session.created" && this.matchesPendingFollowup(event.properties.info)) {
             return true
@@ -1818,15 +1825,12 @@ export class KiloProvider implements vscode.WebviewViewProvider, TelemetryProper
         this.memory.fetch(),
         this.seedSessionStatusMap(),
       ])
-      this.cachedGitRepo = await hasGit(this.client!, this.getWorkspaceDirectory())
-      this.postMessage({ type: "gitStatus", repo: this.cachedGitRepo })
+      await this.refreshGitStatus(this.getWorkspaceDirectory())
       this.sendNotificationSettings()
       this.sendTimelineSetting()
       this.postMessage(buildThroughputSettingMessage())
       this.postMessage({ type: "extensionDataReady" })
 
-      if (this.cachedGitRepo) this.startStatsPolling()
-
       console.log("[Kilo New] KiloProvider: ✅ initializeConnection completed successfully")
     } catch (error) {
       console.error("[Kilo New] KiloProvider: ❌ Failed to initialize connection:", error)
@@ -1887,6 +1891,7 @@ export class KiloProvider implements vscode.WebviewViewProvider, TelemetryProper
   /** Non-blocking: refresh session metadata + status for the webview after switching. */
   private refreshSessionDetails(sessionID: string, dir: string, signal?: AbortSignal): void {
     if (!this.client) return
+    void this.refreshGitStatus(dir)
     const revision = this.revisions.get(sessionID)
     const refresh = (this.refreshes.get(sessionID) ?? 0) + 1
     this.refreshes.set(sessionID, refresh)
@@ -2102,10 +2107,12 @@ export class KiloProvider implements vscode.WebviewViewProvider, TelemetryProper
   private async flushPendingSessionRefresh(reason: string): Promise<void> {
     if (!this.pendingSessionRefresh) return
     console.log("[Kilo New] KiloProvider: 🔄 Flushing deferred sessions refresh", { reason })
+    const scope = this.opts.projectQualifier?.()?.projectId
+    if (scope !== undefined) this.projectID = undefined
     const ctx = this.sessionRefreshContext
     try {
       const resolved = await flushPendingSessionRefreshUtil(ctx)
-      if (resolved) this.projectID = resolved
+      if (resolved && scope === this.opts.projectQualifier?.()?.projectId) this.projectID = resolved
     } catch (error) {
       console.error("[Kilo New] KiloProvider: Failed to flush session refresh:", error)
     }
@@ -2116,10 +2123,12 @@ export class KiloProvider implements vscode.WebviewViewProvider, TelemetryProper
    * Handle loading all sessions.
    */
   private async handleLoadSessions(): Promise<void> {
+    const scope = this.opts.projectQualifier?.()?.projectId
+    if (scope !== undefined) this.projectID = undefined
     const ctx = this.sessionRefreshContext
     try {
       const resolved = await loadSessionsUtil(ctx)
-      if (resolved) this.projectID = resolved
+      if (resolved && scope === this.opts.projectQualifier?.()?.projectId) this.projectID = resolved
     } catch (error) {
       console.error("[Kilo New] KiloProvider: Failed to load sessions:", error)
       this.postMessage({
@@ -2701,6 +2710,15 @@ export class KiloProvider implements vscode.WebviewViewProvider, TelemetryProper
     this.postMessage(message)
   }
 
+  private async fetchAndSendSpeechToTextModels(): Promise<void> {
+    const result = await fetchSpeechToTextModels(this.connectionService, this.getWorkspaceDirectory())
+    if (!result.ok) {
+      this.postMessage({ type: "speechToTextModelsLoaded" as const, models: [...SPEECH_TO_TEXT_MODELS] })
+      return
+    }
+    this.postMessage({ type: "speechToTextModelsLoaded" as const, models: result.models })
+  }
+
   /**
    * Seed sessionStatusMap with current session statuses on connect.
    * Without this, the Settings panel (which has no tracked sessions) would see
@@ -3944,6 +3962,7 @@ export class KiloProvider implements vscode.WebviewViewProvider, TelemetryProper
       disposeGlobal: () => this.disposeGlobal(),
       fetchAndSendProviders: () => this.fetchAndSendProviders(),
       fetchAndSendAgents: () => this.fetchAndSendAgents(),
+      fetchAndSendSpeechToTextModels: () => this.fetchAndSendSpeechToTextModels(),
     }
   }
 
@@ -4293,9 +4312,10 @@ export class KiloProvider implements vscode.WebviewViewProvider, TelemetryProper
     // Drop session events from other projects before any tracking logic.
     // This must come first: the trackedSessionIds guard below would otherwise
     // let a foreign session through if it was accidentally tracked.
-    if (!isLegacySyncEvent(event) && isEventFromForeignProject(event, this.projectID)) return
+    if (directory && !this.isCurrentProjectDirectory(directory)) return
     if (
       this.projectID &&
+      (!this.opts.projectQualifier || !directory) &&
       (event.type === "session.created" || event.type === "session.updated") &&
       event.properties.info.projectID !== undefined &&
       event.properties.info.projectID !== null &&
@@ -4354,6 +4374,8 @@ export class KiloProvider implements vscode.WebviewViewProvider, TelemetryProper
     )
       return
 
+    if (event.type === "message.part.updated") this.refreshGitStatusFromPart(event, sessionID)
+
     if (event.type === "session.updated" && typeof event.properties.info.cost === "number") {
       const cost = this.costs.setSessionCost(event.properties.sessionID, event.properties.info.cost)
       this.requestCostAlert(event.properties.sessionID, cost)
@@ -4724,6 +4746,79 @@ export class KiloProvider implements vscode.WebviewViewProvider, TelemetryProper
     return undefined
   }
 
+  private isCurrentProjectDirectory(directory: string): boolean {
+    if (!this.opts.projectQualifier?.()) return true
+    const dirs = [this.getRootDirectory(), ...(this.opts.worktreeDirectories?.() ?? [])]
+    return dirs.some((dir) => sameDirectory(dir, directory))
+  }
+
+  private isCurrentProjectSession(sessionID: string): boolean {
+    if (!this.opts.projectQualifier || !this.opts.routeService) return true
+    const directory = this.opts.routeService.trySessionDirectory(sessionID)
+    return !directory || this.isCurrentProjectDirectory(directory)
+  }
+
+  private refreshGitStatusFromPart(
+    event: Extract<ProviderEvent, { type: "message.part.updated" }>,
+    sessionID?: string,
+  ) {
+    const part = event.properties.part as {
+      type?: string
+      metadata?: Record<string, unknown>
+      state?: { status?: string; input?: Record<string, unknown>; metadata?: Record<string, unknown> }
+    }
+    if (part.type !== "tool" || part.state?.status !== "completed") return
+    const values = [part.metadata?.filepath, part.state?.metadata?.filepath, part.state?.input?.filePath]
+    const file = values.find((value): value is string => typeof value === "string" && value.length > 0)
+    if (!file) return
+    const base = this.getWorkspaceDirectory(sessionID)
+    const value = file.split(",")[0].trim()
+    const pathName = path.isAbsolute(value) ? value : path.resolve(base, value)
+    const directory = path.dirname(pathName)
+    if (!this.isCurrentProjectGitDirectory(directory, sessionID)) return
+    void this.refreshGitStatus(directory)
+  }
+
+  private isCurrentProjectGitDirectory(directory: string, sessionID?: string): boolean {
+    const roots = this.opts.projectQualifier?.()
+      ? [this.getRootDirectory(), ...(this.opts.worktreeDirectories?.() ?? [])]
+      : [this.getWorkspaceDirectory(sessionID)]
+    return roots.some((root) => {
+      const rel = path.relative(canonicalizePath(root), canonicalizePath(directory))
+      return rel === "" || (!path.isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${path.sep}`))
+    })
+  }
+
+  public async refreshGitStatus(directory = this.getWorkspaceDirectory()): Promise<void> {
+    const client = this.client
+    if (!client) return
+    const revision = ++this.gitStatusRevision
+    const repo = await hasGit(client, directory)
+    const root = await this.resolveGitRoot(directory)
+    if (revision !== this.gitStatusRevision) return
+    const found = repo || root !== undefined
+    const target = root ?? directory
+    if (!this.cachedGitDirectory || !sameDirectory(this.cachedGitDirectory, target)) this.cachedStats = null
+    this.cachedGitDirectory = target
+    this.cachedGitRepo = found
+    this.postMessage({ type: "gitStatus", repo: found })
+    if (found) {
+      if (!this.statsPoller) this.startStatsPolling()
+      return
+    }
+    this.statsPoller?.stop()
+    this.statsGitOps?.dispose()
+    this.statsPoller = null
+    this.statsGitOps = null
+  }
+
+  private async resolveGitRoot(directory: string): Promise<string | undefined> {
+    const git = this.statsGitOps ?? new GitOps({ log: () => {} })
+    const root = await git.root(directory)
+    if (!this.statsGitOps) git.dispose()
+    return root
+  }
+
   private getContextDirectory(): string {
     return resolveContextDirectory({
       currentSessionID: this.currentSession?.id,
@@ -4797,7 +4892,7 @@ export class KiloProvider implements vscode.WebviewViewProvider, TelemetryProper
       workerUri: webview.asWebviewUri(vscode.Uri.joinPath(this.extensionUri, "dist", "shiki-worker.js")),
       title: "Kilo Code",
       port: this.connectionService.getServerInfo()?.port,
-      extraStyles: `.container { height: 100%; display: flex; flex-direction: column; height: 100vh; border-right: 1px solid var(--border-weak-base); }`,
+      extraStyles: `.container { height: 100vh; }`,
     })
   }
 
@@ -4833,7 +4928,7 @@ export class KiloProvider implements vscode.WebviewViewProvider, TelemetryProper
     this.statsGitOps = git
     this.statsPoller = new GitStatsPoller({
       getWorktrees: () => [],
-      getWorkspaceRoot: () => getWorkspaceRoot(),
+      getWorkspaceRoot: () => this.cachedGitDirectory ?? this.getWorkspaceDirectory(this.currentSession?.id),
       localDiff: (dir, base) => localDiffSummary(git, dir, base),
       git,
       onStats: () => {},
diff --git a/packages/kilo-vscode/src/agent-manager/AgentManagerProvider.ts b/packages/kilo-vscode/src/agent-manager/AgentManagerProvider.ts
index 39b844f9894..069783c53fc 100644
--- a/packages/kilo-vscode/src/agent-manager/AgentManagerProvider.ts
+++ b/packages/kilo-vscode/src/agent-manager/AgentManagerProvider.ts
@@ -395,6 +395,7 @@ export class AgentManagerProvider implements Disposable {
         this.panelSessions.clear()
         void ctx.sessions.abortSessions(ids).catch((err) => this.log("Failed to abort sessions on panel close:", err))
         this.statsPoller.stop()
+        this.projectPollers.dispose()
         this.prBridge.poller.stop()
         this.diffs.stop()
         this.activeSessionId = undefined
@@ -450,12 +451,14 @@ export class AgentManagerProvider implements Disposable {
 
   /** Initialize an expanded background project and push its state (no panel wiring). */
   private initExpanded(ctx: ProjectContext): void {
-    void initContextState(ctx, (...args) => this.log(...args)).then((result) => {
-      if (!result.current) return
-      registerProjectSessions(ctx, this.panel?.sessions)
-      this.pushState(ctx)
-      this.projectPollers.sync(this.contexts)
-    })
+    void initContextState(ctx, (...args) => this.log(...args))
+      .then((result) => {
+        if (!result.current) return
+        registerProjectSessions(ctx, this.panel?.sessions)
+        this.pushState(ctx)
+        this.projectPollers.sync(this.contexts)
+      })
+      .catch((err) => this.log("Failed to initialize expanded project:", err))
   }
 
   // Message interceptor
@@ -1047,6 +1050,7 @@ export class AgentManagerProvider implements Disposable {
     if (!req) return
     if (directory) {
       req.directory = directory
+      req.projectId ??= this.contexts.byDirectory(directory)?.id
     }
     void this.startToolRequest(req)
   }
@@ -1555,7 +1559,11 @@ export class AgentManagerProvider implements Disposable {
     void this.sendRepoInfo()
     if (!reactivateProject(ctx, this.panel?.sessions, (c) => this.pushState(c)))
       this.stateReady = this.initializeState()
-    else this.projectPollers.sync(this.contexts)
+    else {
+      this.panel?.sessions.refreshSessions()
+      this.projectPollers.sync(this.contexts)
+    }
+    this.panel?.sessions.refreshGitStatus?.()
   }
   private onWorkspaceChanged(): void {
     if (this.contexts.syncPinned()) {
@@ -1567,11 +1575,20 @@ export class AgentManagerProvider implements Disposable {
   }
 
   private pushProjects(): void {
+    const projects = this.contexts.snapshots()
     this.postToWebview({
       type: "agentManager.projects",
       multiProject: this.host.multiProject(),
-      projects: this.contexts.snapshots(),
+      projects,
     })
+    if (this.panel) {
+      for (const project of projects) {
+        if (project.active || !project.expanded || !project.trusted || project.missing) continue
+        if (this.contexts.get(project.id)) continue
+        const ctx = this.contexts.expand(project.id)
+        if (ctx) this.initExpanded(ctx)
+      }
+    }
     this.projectPollers.sync(this.contexts)
   }
 
diff --git a/packages/kilo-vscode/src/agent-manager/GitOps.ts b/packages/kilo-vscode/src/agent-manager/GitOps.ts
index 92a2984b5a9..ea26906b893 100644
--- a/packages/kilo-vscode/src/agent-manager/GitOps.ts
+++ b/packages/kilo-vscode/src/agent-manager/GitOps.ts
@@ -171,6 +171,10 @@ export class GitOps {
     return this.raw(["rev-parse", "--abbrev-ref", "HEAD"], cwd).catch(() => "")
   }
 
+  async root(cwd: string): Promise<string | undefined> {
+    return this.raw(["rev-parse", "--show-toplevel"], cwd).catch(() => undefined)
+  }
+
   /**
    * Resolve the remote name for a branch. Checks (in order):
    * 1. The configured upstream's remote (e.g. upstream from `upstream/main`)
diff --git a/packages/kilo-vscode/src/agent-manager/host.ts b/packages/kilo-vscode/src/agent-manager/host.ts
index f8e8cee3a64..296cb70caf3 100644
--- a/packages/kilo-vscode/src/agent-manager/host.ts
+++ b/packages/kilo-vscode/src/agent-manager/host.ts
@@ -66,6 +66,8 @@ export interface SessionProvider {
   isSessionRouteAmbiguous?(sessionId: string): boolean
   /** Exact directory for a project-qualified session ref, or undefined. */
   routeSessionDirectoryFor?(ref: SessionRef): string | undefined
+  /** Re-check Git capability for the active project/session directory. */
+  refreshGitStatus?(): void
   dispose(): void
 }
 
diff --git a/packages/kilo-vscode/src/agent-manager/project/contexts.ts b/packages/kilo-vscode/src/agent-manager/project/contexts.ts
index a5ed3f34451..95a16d7050a 100644
--- a/packages/kilo-vscode/src/agent-manager/project/contexts.ts
+++ b/packages/kilo-vscode/src/agent-manager/project/contexts.ts
@@ -32,6 +32,7 @@ interface ContextsOptions {
   registry: {
     list(): StoredProject[]
     get(id: string): StoredProject | undefined
+    expanded?(id: string): boolean | undefined
   }
   /** Registry trust lookup for non-pinned projects. */
   trusted: (id: string) => boolean
@@ -44,7 +45,7 @@ interface ContextsOptions {
 export class ProjectContexts {
   private readonly contexts = new Map<string, ProjectContext>()
   private activeId: string | undefined
-  private readonly expanded = new Set<string>()
+  private readonly expansion = new Map<string, boolean>()
 
   constructor(private readonly opts: ContextsOptions) {}
 
@@ -83,7 +84,7 @@ export class ProjectContexts {
     const pinned = this.pinned()
     if (pinned) {
       this.activeId = pinned.id
-      this.expanded.add(pinned.id)
+      this.rememberExpansion(pinned.id, true)
       return pinned
     }
     if (!this.opts.enabled()) return undefined
@@ -91,7 +92,7 @@ export class ProjectContexts {
     if (!first) return undefined
     const ctx = this.ensure(first.id, first.root, false)
     this.activeId = ctx.id
-    this.expanded.add(ctx.id)
+    this.rememberExpansion(ctx.id, false)
     return ctx
   }
 
@@ -140,7 +141,12 @@ export class ProjectContexts {
   }
 
   isExpanded(id: string): boolean {
-    return this.expanded.has(id)
+    const value = this.expansion.get(id)
+    if (value !== undefined) return value
+    const stored = this.opts.registry.expanded?.(id)
+    if (stored !== undefined) return stored
+    const root = this.opts.workspaceRoot()
+    return root !== undefined && projectIdFor(canonicalizePath(root)) === id
   }
 
   /** Make a project the active context and expand it. Returns undefined when not allowed. */
@@ -148,6 +154,7 @@ export class ProjectContexts {
     const ctx = this.usableCtx(id)
     if (!ctx) return undefined
     this.activeId = id
+    this.rememberExpansion(id, false)
     return ctx
   }
 
@@ -155,12 +162,12 @@ export class ProjectContexts {
   expand(id: string): ProjectContext | undefined {
     const ctx = this.usableCtx(id)
     if (!ctx) return undefined
-    this.expanded.add(id)
+    this.expansion.set(id, true)
     return ctx
   }
 
   collapse(id: string): void {
-    this.expanded.delete(id)
+    this.expansion.set(id, false)
     if (this.isActive(id)) return
     this.contexts.get(id)?.suspend()
   }
@@ -169,10 +176,10 @@ export class ProjectContexts {
   disable(): ProjectContext | undefined {
     const pinned = this.pinned()
     this.activeId = pinned?.id
-    if (pinned) this.expanded.add(pinned.id)
+    if (pinned) this.expansion.set(pinned.id, true)
     for (const ctx of this.contexts.values()) {
       if (ctx.pinned) continue
-      this.expanded.delete(ctx.id)
+      this.expansion.set(ctx.id, false)
       ctx.suspend()
       // Match remove()/syncPinned(): drop the routes too, otherwise the shared
       // route service accumulates entries for every disabled project.
@@ -194,7 +201,7 @@ export class ProjectContexts {
   async remove(id: string): Promise<boolean> {
     const ctx = this.contexts.get(id)
     if (!ctx || ctx.pinned) return false
-    this.expanded.delete(id)
+    this.expansion.delete(id)
     if (this.activeId === id) this.activeId = undefined
     this.contexts.delete(id)
     this.opts.remove?.(id)
@@ -215,7 +222,7 @@ export class ProjectContexts {
     for (const [id, ctx] of [...this.contexts]) {
       if (!ctx.pinned) continue
       this.contexts.delete(id)
-      this.expanded.delete(id)
+      this.expansion.delete(id)
       if (this.activeId === id) this.activeId = undefined
       this.opts.remove?.(id)
       ctx.suspend()
@@ -241,26 +248,32 @@ export class ProjectContexts {
     const id = ctx?.id ?? stored!.id
     const root = ctx?.root ?? stored!.root
     const pinned = ctx?.pinned ?? false
+    const missing = ctx ? ctx.missing() : !(this.opts.deps.exists ?? fs.existsSync)(root)
     return {
       id,
       root,
       label: stored?.label || path.basename(root) || root,
       pinned,
       active: this.isActive(id),
-      expanded: this.isExpanded(id),
+      expanded: !missing && this.isExpanded(id),
       initialized: ctx?.loaded ?? false,
       trusted: pinned || (stored?.trusted ?? false),
-      missing: ctx ? ctx.missing() : !(this.opts.deps.exists ?? fs.existsSync)(root),
+      missing,
     }
   }
 
+  private rememberExpansion(id: string, fallback: boolean): void {
+    if (this.expansion.has(id)) return
+    this.expansion.set(id, this.opts.registry.expanded?.(id) ?? fallback)
+  }
+
   async dispose(): Promise<void> {
     for (const ctx of this.contexts.values()) {
       this.opts.remove?.(ctx.id)
       await ctx.dispose()
     }
     this.contexts.clear()
-    this.expanded.clear()
+    this.expansion.clear()
     this.activeId = undefined
   }
 }
diff --git a/packages/kilo-vscode/src/agent-manager/project/messages.ts b/packages/kilo-vscode/src/agent-manager/project/messages.ts
index 9bf8c542f8a..4349f709c4a 100644
--- a/packages/kilo-vscode/src/agent-manager/project/messages.ts
+++ b/packages/kilo-vscode/src/agent-manager/project/messages.ts
@@ -189,9 +189,15 @@ function selectProject(id: string, deps: ProjectMessageDeps): void {
 
 async function setExpanded(id: string, expanded: boolean, deps: ProjectMessageDeps): Promise<void> {
   if (disabled(deps)) return
+  const ctx = expanded ? deps.contexts.usable(id) : deps.contexts.resolve(id)
+  if (!ctx) {
+    deps.push()
+    return
+  }
+  await deps.registry.setExpanded(id, expanded)
   if (expanded) {
-    const ctx = deps.contexts.expand(id)
-    if (ctx) deps.expand(ctx)
+    const next = deps.contexts.expand(id)
+    if (next) deps.expand(next)
   }
   if (!expanded) deps.contexts.collapse(id)
   deps.push()
diff --git a/packages/kilo-vscode/src/agent-manager/project/registry.ts b/packages/kilo-vscode/src/agent-manager/project/registry.ts
index 9b11a115136..1a727db40be 100644
--- a/packages/kilo-vscode/src/agent-manager/project/registry.ts
+++ b/packages/kilo-vscode/src/agent-manager/project/registry.ts
@@ -1,10 +1,10 @@
 /**
  * ProjectRegistry — global catalog of additional Agent Manager projects.
  *
- * The registry persists only *additional* projects: repositories the user
- * explicitly added through the Agent Manager project picker. The pinned
- * default project is always derived from the current VS Code workspace at
- * runtime and is never stored here.
+ * The registry persists *additional* projects: repositories the user explicitly
+ * added through the Agent Manager project picker. The pinned default project is
+ * always derived from the current VS Code workspace at runtime; only its
+ * accordion preference is stored by id.
  *
  * Storage is injected so the registry stays free of VS Code imports and can
  * be unit-tested with an in-memory store. The file is versioned; corrupt or
@@ -31,11 +31,20 @@ export interface StoredProject {
   /** Whether project-controlled scripts may execute for this project. */
   trusted: boolean
   addedAt: string
+  /** Whether this project accordion should render its body. */
+  expanded?: boolean
 }
 
 interface RegistryFile {
   version: 1
   projects: StoredProject[]
+  /** Expansion state for the pinned workspace project, which is not a catalog entry. */
+  pinnedExpanded?: Record<string, boolean>
+}
+
+interface ParsedRegistry {
+  projects: StoredProject[]
+  pinnedExpanded: Record<string, boolean>
 }
 
 export interface RegistryStorage {
@@ -53,16 +62,17 @@ function valid(entry: unknown): entry is StoredProject {
     typeof e.root === "string" &&
     typeof e.order === "number" &&
     typeof e.trusted === "boolean" &&
-    typeof e.addedAt === "string"
+    typeof e.addedAt === "string" &&
+    (e.expanded === undefined || typeof e.expanded === "boolean")
   )
 }
 
-function parse(raw: unknown, log: (msg: string) => void): StoredProject[] {
-  if (!raw || typeof raw !== "object") return []
+function parse(raw: unknown, log: (msg: string) => void): ParsedRegistry {
+  if (!raw || typeof raw !== "object") return { projects: [], pinnedExpanded: {} }
   const file = raw as Partial<RegistryFile>
   if (file.version !== VERSION || !Array.isArray(file.projects)) {
     if (file.version !== undefined) log("project registry has an unsupported shape, starting empty")
-    return []
+    return { projects: [], pinnedExpanded: {} }
   }
   const seen = new Set<string>()
   const out: StoredProject[] = []
@@ -72,11 +82,18 @@ function parse(raw: unknown, log: (msg: string) => void): StoredProject[] {
     seen.add(entry.id)
     out.push(entry)
   }
-  return out.sort((a, b) => a.order - b.order)
+  const pinnedExpanded: Record<string, boolean> = {}
+  if (file.pinnedExpanded && typeof file.pinnedExpanded === "object") {
+    for (const [id, expanded] of Object.entries(file.pinnedExpanded)) {
+      if (typeof expanded === "boolean") pinnedExpanded[id] = expanded
+    }
+  }
+  return { projects: out.sort((a, b) => a.order - b.order), pinnedExpanded }
 }
 
 export class ProjectRegistry {
   private projects: StoredProject[] | undefined
+  private pinnedExpanded: Record<string, boolean> | undefined
   private queue: Promise<void> = Promise.resolve()
 
   constructor(
@@ -85,20 +102,26 @@ export class ProjectRegistry {
   ) {}
 
   private load(): StoredProject[] {
-    this.projects ??= parse(this.storage.read(), this.log)
+    if (!this.projects) {
+      const parsed = parse(this.storage.read(), this.log)
+      this.projects = parsed.projects
+      this.pinnedExpanded = parsed.pinnedExpanded
+    }
     return this.projects
   }
 
   /** Fresh re-read + validate/dedupe/sort, used by every mutation. */
-  private fresh(): StoredProject[] {
+  private fresh(): ParsedRegistry {
     return parse(this.storage.read(), this.log)
   }
 
   /** Persist the next catalog and update the cache only after the write succeeds. */
-  private async write(next: StoredProject[]): Promise<void> {
+  private async write(next: StoredProject[], pinnedExpanded: Record<string, boolean>): Promise<void> {
     const file: RegistryFile = { version: VERSION, projects: next }
+    if (Object.keys(pinnedExpanded).length > 0) file.pinnedExpanded = pinnedExpanded
     await this.storage.write(file)
     this.projects = next
+    this.pinnedExpanded = pinnedExpanded
   }
 
   /** Serialize mutations within this instance; a failed mutation does not poison the queue. */
@@ -119,6 +142,14 @@ export class ProjectRegistry {
     return this.load().find((p) => p.id === id)
   }
 
+  /** Return explicit expansion state, if one has been persisted. */
+  expanded(id: string): boolean | undefined {
+    const project = this.get(id)
+    if (project) return project.expanded
+    this.load()
+    return this.pinnedExpanded?.[id]
+  }
+
   /** Register an additional project. Throws when the id is already registered. */
   add(input: { id: string; root: string; label?: string }): Promise<StoredProject> {
     return this.run(() => this.doAdd(input))
@@ -126,8 +157,9 @@ export class ProjectRegistry {
 
   private async doAdd(input: { id: string; root: string; label?: string }): Promise<StoredProject> {
     const current = this.fresh()
-    if (current.find((p) => p.id === input.id)) throw new Error("That repository is already registered as a project.")
-    const order = current.reduce((max, p) => Math.max(max, p.order), 0) + 1
+    if (current.projects.find((p) => p.id === input.id))
+      throw new Error("That repository is already registered as a project.")
+    const order = current.projects.reduce((max, p) => Math.max(max, p.order), 0) + 1
     const project: StoredProject = {
       id: input.id,
       root: input.root,
@@ -136,7 +168,7 @@ export class ProjectRegistry {
       trusted: false,
       addedAt: new Date().toISOString(),
     }
-    await this.write([...current, project])
+    await this.write([...current.projects, project], current.pinnedExpanded)
     return project
   }
 
@@ -147,9 +179,11 @@ export class ProjectRegistry {
 
   private async doRemove(id: string): Promise<boolean> {
     const current = this.fresh()
-    const next = current.filter((p) => p.id !== id)
-    if (next.length === current.length) return false
-    await this.write(next)
+    const next = current.projects.filter((p) => p.id !== id)
+    if (next.length === current.projects.length) return false
+    const pinnedExpanded = { ...current.pinnedExpanded }
+    delete pinnedExpanded[id]
+    await this.write(next, pinnedExpanded)
     return true
   }
 
@@ -159,8 +193,11 @@ export class ProjectRegistry {
 
   private async doSetTrusted(id: string, trusted: boolean): Promise<boolean> {
     const current = this.fresh()
-    if (!current.find((p) => p.id === id)) return false
-    await this.write(current.map((p) => (p.id === id ? { ...p, trusted } : p)))
+    if (!current.projects.find((p) => p.id === id)) return false
+    await this.write(
+      current.projects.map((p) => (p.id === id ? { ...p, trusted } : p)),
+      current.pinnedExpanded,
+    )
     return true
   }
 
@@ -170,8 +207,29 @@ export class ProjectRegistry {
 
   private async doSetLabel(id: string, label: string | undefined): Promise<boolean> {
     const current = this.fresh()
-    if (!current.find((p) => p.id === id)) return false
-    await this.write(current.map((p) => (p.id === id ? { ...p, label } : p)))
+    if (!current.projects.find((p) => p.id === id)) return false
+    await this.write(
+      current.projects.map((p) => (p.id === id ? { ...p, label } : p)),
+      current.pinnedExpanded,
+    )
+    return true
+  }
+
+  setExpanded(id: string, expanded: boolean): Promise<boolean> {
+    return this.run(() => this.doSetExpanded(id, expanded))
+  }
+
+  private async doSetExpanded(id: string, expanded: boolean): Promise<boolean> {
+    const current = this.fresh()
+    if (current.projects.some((p) => p.id === id)) {
+      await this.write(
+        current.projects.map((p) => (p.id === id ? { ...p, expanded } : p)),
+        current.pinnedExpanded,
+      )
+      return true
+    }
+    const pinnedExpanded = { ...current.pinnedExpanded, [id]: expanded }
+    await this.write(current.projects, pinnedExpanded)
     return true
   }
 }
diff --git a/packages/kilo-vscode/src/agent-manager/provider-multi-version.ts b/packages/kilo-vscode/src/agent-manager/provider-multi-version.ts
index 37a9fe93a14..41cc02049eb 100644
--- a/packages/kilo-vscode/src/agent-manager/provider-multi-version.ts
+++ b/packages/kilo-vscode/src/agent-manager/provider-multi-version.ts
@@ -50,6 +50,7 @@ export async function createMultiVersion(
   // Notify webview that multi-version creation has started
   host.post({
     type: "agentManager.multiVersionProgress",
+    projectId: ctx.id,
     status: "creating",
     total: versions,
     completed: 0,
@@ -78,6 +79,7 @@ export async function createMultiVersion(
     // Update progress
     host.post({
       type: "agentManager.multiVersionProgress",
+      projectId: ctx.id,
       status: "creating",
       total: versions,
       completed: created.length,
@@ -86,11 +88,19 @@ export async function createMultiVersion(
   }
 
   // Phase 2: Send the initial prompt to all sessions, or clear busy state if no text.
-  await sendInitialPrompts(host, created, models, { providerID, modelID }, { text, agent, variant: msg.variant, files })
+  await sendInitialPrompts(
+    host,
+    ctx.id,
+    created,
+    models,
+    { providerID, modelID },
+    { text, agent, variant: msg.variant, files },
+  )
 
   // Notify completion
   host.post({
     type: "agentManager.multiVersionProgress",
+    projectId: ctx.id,
     status: "done",
     total: versions,
     completed: created.length,
@@ -172,6 +182,7 @@ async function createVersion(
   if (earlyProviderID && earlyModelID) {
     host.post({
       type: "agentManager.setSessionModel",
+      projectId: ctx.id,
       sessionId: session.id,
       providerID: earlyProviderID,
       modelID: earlyModelID,
@@ -232,6 +243,7 @@ async function reconcileSandbox(
 /** Fan the initial prompt out to every created session, throttled between sends. */
 async function sendInitialPrompts(
   host: MultiVersionHost,
+  projectId: string,
   created: CreatedVersion[],
   models: VersionSpec["models"],
   resolved: { providerID: string | undefined; modelID: string | undefined },
@@ -254,7 +266,7 @@ async function sendInitialPrompts(
         modelID: msg.modelID,
       })
     }
-    host.post({ type: "agentManager.sendInitialMessage", ...msg })
+    host.post({ type: "agentManager.sendInitialMessage", projectId, ...msg })
     if (input.text && i < messages.length - 1) {
       await new Promise((resolve) => setTimeout(resolve, 300))
     }
diff --git a/packages/kilo-vscode/src/agent-manager/tool-start.ts b/packages/kilo-vscode/src/agent-manager/tool-start.ts
index 927a6495370..91af753f991 100644
--- a/packages/kilo-vscode/src/agent-manager/tool-start.ts
+++ b/packages/kilo-vscode/src/agent-manager/tool-start.ts
@@ -19,6 +19,7 @@ export interface ToolTask {
 
 export interface ToolRequest {
   requestID: string
+  projectId?: string
   sessionID?: string
   directory?: string
   sandboxInheritanceToken?: string
@@ -234,7 +235,14 @@ export async function startFromTool(deps: ToolDeps, req: ToolRequest): Promise<v
   const state = { ok: 0 }
   const source = { sandboxInheritanceToken: req.sandboxInheritanceToken }
 
-  deps.post({ type: "agentManager.multiVersionProgress", status: "creating", total, completed: 0, groupId })
+  deps.post({
+    type: "agentManager.multiVersionProgress",
+    projectId: req.projectId,
+    status: "creating",
+    total,
+    completed: 0,
+    groupId,
+  })
   for (let i = 0; i < req.tasks.length; i++) {
     const task = req.tasks[i]!
     try {
@@ -248,10 +256,24 @@ export async function startFromTool(deps: ToolDeps, req: ToolRequest): Promise<v
       deps.log("Agent Manager tool task failed", msg)
       deps.post({ type: "error", message: `Agent Manager tool task failed: ${msg}` })
     }
-    deps.post({ type: "agentManager.multiVersionProgress", status: "creating", total, completed: state.ok, groupId })
+    deps.post({
+      type: "agentManager.multiVersionProgress",
+      projectId: req.projectId,
+      status: "creating",
+      total,
+      completed: state.ok,
+      groupId,
+    })
   }
 
-  deps.post({ type: "agentManager.multiVersionProgress", status: "done", total, completed: state.ok, groupId })
+  deps.post({
+    type: "agentManager.multiVersionProgress",
+    projectId: req.projectId,
+    status: "done",
+    total,
+    completed: state.ok,
+    groupId,
+  })
   if (state.ok === 0) deps.error(`Failed to start any Agent Manager sessions for request ${req.requestID}.`)
   deps.log(`Agent Manager tool request ${req.requestID} complete: ${state.ok}/${total}`)
 }
@@ -299,6 +321,7 @@ export function parseToolRequest(value: unknown): ToolRequest | undefined {
   if (parsed.length !== limited.length) return undefined
   return {
     requestID: typeof value.requestID === "string" ? value.requestID : `am-${Date.now()}`,
+    projectId: typeof value.projectId === "string" ? value.projectId : undefined,
     sessionID: typeof value.sessionID === "string" ? value.sessionID : undefined,
     directory: typeof value.directory === "string" ? value.directory : undefined,
     sandboxInheritanceToken:
diff --git a/packages/kilo-vscode/src/agent-manager/types.ts b/packages/kilo-vscode/src/agent-manager/types.ts
index 3a2b555e355..5f08325a9fe 100644
--- a/packages/kilo-vscode/src/agent-manager/types.ts
+++ b/packages/kilo-vscode/src/agent-manager/types.ts
@@ -258,6 +258,8 @@ interface SessionClosedMessage {
 
 interface MultiVersionProgressMessage {
   type: "agentManager.multiVersionProgress"
+  /** Owning project; absent in single-project mode. */
+  projectId?: string
   status: "creating" | "done"
   total: number
   completed: number
@@ -266,6 +268,8 @@ interface MultiVersionProgressMessage {
 
 interface SetSessionModelMessage {
   type: "agentManager.setSessionModel"
+  /** Owning project; absent in single-project mode. */
+  projectId?: string
   sessionId: string
   providerID: string
   modelID: string
@@ -273,6 +277,8 @@ interface SetSessionModelMessage {
 
 interface SendInitialMessage {
   type: "agentManager.sendInitialMessage"
+  /** Owning project; absent in single-project mode. */
+  projectId?: string
   sessionId: string
   worktreeId: string
   text?: string
@@ -791,6 +797,7 @@ interface FileSourceIn {
 
 interface SendMessageIn {
   type: "sendMessage"
+  projectId?: string
   text: string
   messageID?: string
   sessionID?: string
diff --git a/packages/kilo-vscode/src/agent-manager/vscode-host.ts b/packages/kilo-vscode/src/agent-manager/vscode-host.ts
index 4e1528f8a9b..a98f679d89e 100644
--- a/packages/kilo-vscode/src/agent-manager/vscode-host.ts
+++ b/packages/kilo-vscode/src/agent-manager/vscode-host.ts
@@ -151,6 +151,7 @@ export class VscodeHost implements Host {
       unregisterSessionRoute: (ref) => provider.unregisterSessionRoute(ref),
       isSessionRouteAmbiguous: (sessionId) => provider.isSessionRouteAmbiguous(sessionId),
       routeSessionDirectoryFor: (ref) => provider.routeSessionDirectoryFor(ref),
+      refreshGitStatus: () => void provider.refreshGitStatus(),
       dispose: () => provider.dispose(),
     }
 
diff --git a/packages/kilo-vscode/src/kilo-provider-utils.ts b/packages/kilo-vscode/src/kilo-provider-utils.ts
index c9825cb7713..41ea85380de 100644
--- a/packages/kilo-vscode/src/kilo-provider-utils.ts
+++ b/packages/kilo-vscode/src/kilo-provider-utils.ts
@@ -661,7 +661,10 @@ export function mapCloudSessionMessageToWebviewMessage(message: CloudSessionMess
  * Returns true when the event carries a projectID that does not match the expected one.
  * When expectedProjectID is undefined (not yet resolved), nothing is filtered.
  */
-export function isEventFromForeignProject(event: StreamEvent, expectedProjectID: string | undefined): boolean {
+export function isEventFromForeignProject(
+  event: StreamEvent | SyncPayload,
+  expectedProjectID: string | undefined,
+): boolean {
   if (!expectedProjectID || event.type !== "sync") return false
   if (event.name === "session.created.1" || event.name === "session.deleted.1") {
     return event.data.info.projectID !== expectedProjectID
diff --git a/packages/kilo-vscode/src/kilo-provider/early-message.ts b/packages/kilo-vscode/src/kilo-provider/early-message.ts
index f67a2144fa1..abf79b49a02 100644
--- a/packages/kilo-vscode/src/kilo-provider/early-message.ts
+++ b/packages/kilo-vscode/src/kilo-provider/early-message.ts
@@ -17,6 +17,7 @@ type Ctx = {
   exportTranscript: (sessionID: string) => Promise<void>
   copy: (text: string) => PromiseLike<void>
   openSessions: (ids: string[]) => void
+  speechToTextModels: () => Promise<void>
 }
 
 export async function routeEarlyMessage(
@@ -64,6 +65,10 @@ export async function routeEarlyMessage(
     ctx.post(buildThroughputSettingMessage())
     return true
   }
+  if (message.type === "requestSpeechToTextModels") {
+    await ctx.speechToTextModels()
+    return true
+  }
   if (message.type === "requestBrowserSettings") {
     ctx.browserSettings()
     return true
diff --git a/packages/kilo-vscode/src/kilo-provider/git-status.ts b/packages/kilo-vscode/src/kilo-provider/git-status.ts
index 12e324e529a..e4ef22b5e45 100644
--- a/packages/kilo-vscode/src/kilo-provider/git-status.ts
+++ b/packages/kilo-vscode/src/kilo-provider/git-status.ts
@@ -1,8 +1,8 @@
 import type { KiloClient } from "@kilocode/sdk/v2/client"
 
 export async function hasGit(client: KiloClient, directory: string): Promise<boolean> {
-  return client.project
-    .current({ directory })
+  return Promise.resolve()
+    .then(() => client.project.current({ directory }))
     .then((r) => r.data?.vcs === "git")
     .catch(() => false)
 }
diff --git a/packages/kilo-vscode/src/kilo-provider/handlers/auth.ts b/packages/kilo-vscode/src/kilo-provider/handlers/auth.ts
index db6e9e6d7df..07ae712b902 100644
--- a/packages/kilo-vscode/src/kilo-provider/handlers/auth.ts
+++ b/packages/kilo-vscode/src/kilo-provider/handlers/auth.ts
@@ -15,6 +15,7 @@ export interface AuthContext {
   disposeGlobal(): Promise<void>
   fetchAndSendProviders(): Promise<void>
   fetchAndSendAgents(): Promise<void>
+  fetchAndSendSpeechToTextModels(): Promise<void>
 }
 
 /**
@@ -137,6 +138,11 @@ export async function handleSetOrganization(ctx: AuthContext, organizationId: st
   } catch (error) {
     console.error("[Kilo New] KiloProvider: Failed to refresh agents after org switch:", error)
   }
+  try {
+    await ctx.fetchAndSendSpeechToTextModels()
+  } catch (error) {
+    console.error("[Kilo New] KiloProvider: Failed to refresh speech-to-text models after org switch:", error)
+  }
 }
 
 /** Handle profile refresh request. */
diff --git a/packages/kilo-vscode/src/services/cli-backend/server-manager.ts b/packages/kilo-vscode/src/services/cli-backend/server-manager.ts
index 9481897cc5b..76cb5125719 100644
--- a/packages/kilo-vscode/src/services/cli-backend/server-manager.ts
+++ b/packages/kilo-vscode/src/services/cli-backend/server-manager.ts
@@ -29,7 +29,12 @@ export function resolveIndexingEnv(folders: readonly WorkspaceFolderLike[] | und
 }
 
 export function resolveManagedServerEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
-  return { ...env, KILO_DISABLE_CHANNEL_DB: "true" }
+  return {
+    ...env,
+    KILO_DISABLE_CHANNEL_DB: "true",
+    // VS Code does not consume the backend's file.watcher.updated events.
+    KILO_EXPERIMENTAL_DISABLE_FILEWATCHER: "true",
+  }
 }
 
 export class ServerManager {
diff --git a/packages/kilo-vscode/src/speech-to-text/catalog.ts b/packages/kilo-vscode/src/speech-to-text/catalog.ts
new file mode 100644
index 00000000000..fbb24114f74
--- /dev/null
+++ b/packages/kilo-vscode/src/speech-to-text/catalog.ts
@@ -0,0 +1,62 @@
+import type { KiloConnectionService } from "../services/cli-backend/connection-service"
+import { getErrorMessage } from "../kilo-provider-utils"
+import { type SpeechToTextModelDef } from "./models"
+
+const PATH = "/kilo/models/transcriptions"
+
+type CatalogModel = {
+  id: string
+  name: string
+}
+
+export type SpeechToTextCatalogResult = { ok: true; models: SpeechToTextModelDef[] } | { ok: false; error: string }
+
+export async function fetchSpeechToTextModels(
+  connection: KiloConnectionService,
+  dir: string,
+  signal?: AbortSignal,
+): Promise<SpeechToTextCatalogResult> {
+  const cfg = connection.getServerConfig()
+  if (!cfg) return fail("Not connected to the Kilo backend")
+
+  const auth = Buffer.from(`kilo:${cfg.password}`).toString("base64")
+  const url = new URL(PATH, cfg.baseUrl)
+  if (dir) url.searchParams.set("directory", dir)
+
+  try {
+    const res = await fetch(url, { signal, headers: { Authorization: `Basic ${auth}` } })
+    if (!res.ok) return fail(`Failed to fetch speech-to-text models (HTTP ${res.status})`)
+
+    const models = parseSpeechToTextCatalog(await res.json())
+    if (!models) return fail("Invalid speech-to-text model catalog")
+    return { ok: true, models }
+  } catch (err) {
+    return fail(getErrorMessage(err))
+  }
+}
+
+function fail(error: string): SpeechToTextCatalogResult {
+  return { ok: false, error }
+}
+
+export function parseSpeechToTextCatalog(body: unknown): SpeechToTextModelDef[] | undefined {
+  if (!Array.isArray(body)) return undefined
+  const models = body.filter(isCatalogModel).map(toModel)
+  return models.length > 0 ? models : undefined
+}
+
+function isCatalogModel(value: unknown): value is CatalogModel {
+  if (!value || typeof value !== "object") return false
+  const model = value as Record<string, unknown>
+  return typeof model.id === "string" && typeof model.name === "string"
+}
+
+function toModel(model: CatalogModel): SpeechToTextModelDef {
+  const index = model.name.indexOf(":")
+  const provider = index === -1 ? model.id.split("/", 1)[0] || "Kilo Gateway" : model.name.slice(0, index).trim()
+  return {
+    id: model.id,
+    label: index === -1 ? model.name : model.name.slice(index + 1).trim(),
+    provider,
+  }
+}
diff --git a/packages/kilo-vscode/src/speech-to-text/transcribe.ts b/packages/kilo-vscode/src/speech-to-text/transcribe.ts
index 1e978bf028c..bfa0daf590f 100644
--- a/packages/kilo-vscode/src/speech-to-text/transcribe.ts
+++ b/packages/kilo-vscode/src/speech-to-text/transcribe.ts
@@ -54,7 +54,7 @@ export async function transcribeSpeech(
         "Content-Type": "application/json",
       },
       body: JSON.stringify({
-        model: model.id,
+        model: input.model || model.id,
         input_audio: {
           data: input.data,
           format: input.format,
diff --git a/packages/kilo-vscode/tests/package.json b/packages/kilo-vscode/tests/package.json
index 0219e54e36c..9b3ef8d5815 100644
--- a/packages/kilo-vscode/tests/package.json
+++ b/packages/kilo-vscode/tests/package.json
@@ -1,6 +1,6 @@
 {
   "type": "module",
-  "version": "7.4.18",
+  "version": "7.4.20",
   "dependencies": {},
   "devDependencies": {},
   "peerDependencies": {}
diff --git a/packages/kilo-vscode/tests/unit/agent-manager-arch.test.ts b/packages/kilo-vscode/tests/unit/agent-manager-arch.test.ts
index 353070c085b..b4a24df88a7 100644
--- a/packages/kilo-vscode/tests/unit/agent-manager-arch.test.ts
+++ b/packages/kilo-vscode/tests/unit/agent-manager-arch.test.ts
@@ -38,6 +38,7 @@ const TSX_FILES = [
   path.join(ROOT, "webview-ui/agent-manager/ApplyDialog.tsx"),
   path.join(ROOT, "webview-ui/agent-manager/WorktreeItem.tsx"),
   path.join(ROOT, "webview-ui/agent-manager/SectionHeader.tsx"),
+  path.join(ROOT, "webview-ui/agent-manager/SidebarSectionHeader.tsx"),
   path.join(ROOT, "webview-ui/agent-manager/SidebarSearchMenu.tsx"),
   path.join(ROOT, "webview-ui/agent-manager/SidebarToggleButton.tsx"),
   path.join(ROOT, "webview-ui/agent-manager/WorktreeSectionActions.tsx"),
diff --git a/packages/kilo-vscode/tests/unit/agent-manager-focus.test.ts b/packages/kilo-vscode/tests/unit/agent-manager-focus.test.ts
index 1c63c08b4fa..c5c33eea67f 100644
--- a/packages/kilo-vscode/tests/unit/agent-manager-focus.test.ts
+++ b/packages/kilo-vscode/tests/unit/agent-manager-focus.test.ts
@@ -1,6 +1,7 @@
 import { describe, expect, it } from "bun:test"
 import { Window } from "happy-dom"
-import { focusQuestionOption, hasQuestionOption } from "../../webview-ui/agent-manager/focus"
+import { focusQuestionOption, hasQuestionOption, preservesTextFocus } from "../../webview-ui/agent-manager/focus"
+import { isTextControl } from "../../webview-ui/src/utils/focus"
 
 describe("Agent Manager focus", () => {
   it("focuses the first enabled question option", () => {
@@ -53,4 +54,21 @@ describe("Agent Manager focus", () => {
     dock.setAttribute("inert", "")
     expect(hasQuestionOption(root)).toBe(false)
   })
+
+  it("preserves focus for an active editable control", () => {
+    const window = new Window()
+    const rename = window.document.createElement("input")
+    rename.className = "am-worktree-rename-input"
+    const prompt = window.document.createElement("textarea")
+    prompt.className = "prompt-input"
+    const editor = window.document.createElement("div")
+    editor.contentEditable = "plaintext-only"
+    const button = window.document.createElement("button")
+
+    expect(isTextControl(rename)).toBe(true)
+    expect(preservesTextFocus(rename)).toBe(true)
+    expect(preservesTextFocus(prompt)).toBe(false)
+    expect(isTextControl(editor)).toBe(true)
+    expect(isTextControl(button)).toBe(false)
+  })
 })
diff --git a/packages/kilo-vscode/tests/unit/agent-manager-initial-message.test.ts b/packages/kilo-vscode/tests/unit/agent-manager-initial-message.test.ts
index cba84607892..87714a5cac6 100644
--- a/packages/kilo-vscode/tests/unit/agent-manager-initial-message.test.ts
+++ b/packages/kilo-vscode/tests/unit/agent-manager-initial-message.test.ts
@@ -5,6 +5,7 @@ describe("Agent Manager initial message", () => {
   it("forwards the selected variant to sendMessage", () => {
     const msg = initialMessage({
       type: "agentManager.sendInitialMessage",
+      projectId: "project-a",
       sessionId: "session-a",
       worktreeId: "wt-a",
       text: "Fix it",
@@ -16,6 +17,7 @@ describe("Agent Manager initial message", () => {
 
     expect(msg).toEqual({
       type: "sendMessage",
+      projectId: "project-a",
       text: "Fix it",
       sessionID: "session-a",
       providerID: "anthropic",
diff --git a/packages/kilo-vscode/tests/unit/agent-manager-terminal-layout.test.ts b/packages/kilo-vscode/tests/unit/agent-manager-terminal-layout.test.ts
index f30ba800e52..a38ffbb7b99 100644
--- a/packages/kilo-vscode/tests/unit/agent-manager-terminal-layout.test.ts
+++ b/packages/kilo-vscode/tests/unit/agent-manager-terminal-layout.test.ts
@@ -1,8 +1,10 @@
 import { expect, test } from "bun:test"
 import { readFileSync } from "node:fs"
 import { resolve } from "node:path"
+import { clampPanelWidth, maxPanelWidth, minPanelWidth } from "../../webview-ui/agent-manager/side-panel-layout"
 
 const css = readFileSync(resolve(import.meta.dir, "../../webview-ui/agent-manager/agent-manager.css"), "utf8")
+const app = readFileSync(resolve(import.meta.dir, "../../webview-ui/agent-manager/AgentManagerApp.tsx"), "utf8")
 
 test("xterm owns the padding used by FitAddon", () => {
   const host = css.match(/\.am-terminal-host\s*\{([^}]*)\}/)?.[1]
@@ -13,3 +15,22 @@ test("xterm owns the padding used by FitAddon", () => {
   expect(host).not.toMatch(/\bpadding\s*:/)
   expect(term).toMatch(/\bpadding\s*:\s*8px\s*;/)
 })
+
+test("uses one persisted width for the diff and terminal inspector", () => {
+  expect(app).toContain("persisted?.sidePanelWidth")
+  expect(app).toContain("setPanelWidth(pendingSideWidth!)")
+  expect(app).not.toContain("diffWidth")
+  expect(app).not.toContain("terminalWidth")
+})
+
+test("clamps the restored inspector width to the shared layout bounds", () => {
+  expect(clampPanelWidth(undefined, 1200)).toBe(600)
+  expect(clampPanelWidth(500, 1200)).toBe(500)
+  expect(clampPanelWidth(1000, 1000)).toBe(maxPanelWidth(1000))
+  expect(clampPanelWidth(100, 1200)).toBe(minPanelWidth(1200))
+  expect(clampPanelWidth("invalid", 1200)).toBe(600)
+  expect(minPanelWidth(400)).toBe(200)
+  expect(maxPanelWidth(400)).toBe(320)
+  expect(clampPanelWidth(undefined, 400)).toBe(200)
+  expect(clampPanelWidth(360, 400)).toBe(320)
+})
diff --git a/packages/kilo-vscode/tests/unit/agent-project-contexts.test.ts b/packages/kilo-vscode/tests/unit/agent-project-contexts.test.ts
index 97cb9265f96..9c8b6239e91 100644
--- a/packages/kilo-vscode/tests/unit/agent-project-contexts.test.ts
+++ b/packages/kilo-vscode/tests/unit/agent-project-contexts.test.ts
@@ -17,11 +17,14 @@ function stored(id: string, trusted = false): StoredProject {
   }
 }
 
-function setup(opts: { workspace?: string; enabled?: boolean; projects?: StoredProject[] } = {}) {
+function setup(
+  opts: { workspace?: string; enabled?: boolean; projects?: StoredProject[]; expanded?: Record<string, boolean> } = {},
+) {
   const registryProjects = opts.projects ?? []
   const registry = {
     list: () => registryProjects,
     get: (id: string) => registryProjects.find((p) => p.id === id),
+    expanded: (id: string) => opts.expanded?.[id],
   }
   const created: string[] = []
   const contexts = new ProjectContexts({
@@ -207,6 +210,34 @@ describe("ProjectContexts", () => {
     expect(list[1]!.initialized).toBe(false)
   })
 
+  it("keeps the pinned project expanded before active state is initialized", () => {
+    const { contexts } = setup({ workspace: WORKSPACE })
+
+    expect(contexts.isExpanded(PINNED)).toBe(true)
+  })
+
+  it("hydrates persisted project expansion without initializing the project", () => {
+    const extra = stored("prj-extra", true)
+    const { contexts } = setup({
+      workspace: WORKSPACE,
+      enabled: true,
+      projects: [extra],
+      expanded: { [extra.id]: true },
+    })
+
+    const list = contexts.snapshots()
+
+    expect(list[1]!.expanded).toBe(true)
+    expect(list[1]!.initialized).toBe(false)
+    expect(contexts.get(extra.id)).toBeUndefined()
+  })
+
+  it("hydrates a persisted collapsed pinned project", () => {
+    const { contexts } = setup({ workspace: WORKSPACE, expanded: { [PINNED]: false } })
+
+    expect(contexts.snapshots()[0]!.expanded).toBe(false)
+  })
+
   it("hides registry projects from snapshots when the flag is off", () => {
     const extra = stored("prj-extra", true)
     const { contexts } = setup({ workspace: WORKSPACE, enabled: false, projects: [extra] })
diff --git a/packages/kilo-vscode/tests/unit/agent-project-messages.test.ts b/packages/kilo-vscode/tests/unit/agent-project-messages.test.ts
index 762268d78d0..c4a88084a9f 100644
--- a/packages/kilo-vscode/tests/unit/agent-project-messages.test.ts
+++ b/packages/kilo-vscode/tests/unit/agent-project-messages.test.ts
@@ -4,7 +4,7 @@ import * as os from "os"
 import * as path from "path"
 import { execFileSync } from "child_process"
 import { handleProjectMessage, type ProjectMessageDeps } from "../../src/agent-manager/project/messages"
-import { ProjectRegistry } from "../../src/agent-manager/project/registry"
+import { ProjectRegistry, type RegistryStorage } from "../../src/agent-manager/project/registry"
 import { ProjectContexts } from "../../src/agent-manager/project/contexts"
 import { projectIdFor } from "../../src/agent-manager/project/paths"
 import type { AgentManagerInMessage } from "../../src/agent-manager/types"
@@ -20,12 +20,13 @@ function gitRepo(): string {
 function setup(opts: { enabled?: boolean; workspace?: string } = {}) {
   let stored: unknown
   let pickResult: string | undefined
-  const registry = new ProjectRegistry({
+  const storage: RegistryStorage = {
     read: () => stored,
     write: (value) => {
       stored = value
     },
-  })
+  }
+  const registry = new ProjectRegistry(storage)
   const contexts = new ProjectContexts({
     workspaceRoot: () => opts.workspace ?? WORKSPACE,
     registry,
@@ -63,7 +64,7 @@ function setup(opts: { enabled?: boolean; workspace?: string } = {}) {
   const pick = (dir: string | undefined) => {
     pickResult = dir
   }
-  return { registry, contexts, deps, calls, pick }
+  return { registry, contexts, deps, calls, pick, storage }
 }
 
 function msg(type: string, extra: Record<string, unknown> = {}): AgentManagerInMessage {
@@ -170,6 +171,36 @@ describe("handleProjectMessage", () => {
     expect(calls.expand).toEqual([id])
   })
 
+  it("persists project expansion state across registry instances", async () => {
+    const repo = gitRepo()
+    const { deps, registry, storage, calls } = setup()
+    const id = projectIdFor(repo)
+    await registry.add({ id, root: repo })
+    await registry.setTrusted(id, true)
+
+    await handleProjectMessage(msg("agentManager.setProjectExpanded", { projectId: id, expanded: true }), deps)
+
+    const restored = new ProjectRegistry(storage)
+    expect(restored.expanded(id)).toBe(true)
+    expect(restored.get(id)?.expanded).toBe(true)
+
+    await handleProjectMessage(msg("agentManager.setProjectExpanded", { projectId: id, expanded: false }), deps)
+
+    expect(new ProjectRegistry(storage).expanded(id)).toBe(false)
+    expect(calls.push).toBe(2)
+  })
+
+  it("persists the pinned project expansion state without adding it to the catalog", async () => {
+    const { deps, registry, storage } = setup()
+    const id = projectIdFor(WORKSPACE)
+
+    await handleProjectMessage(msg("agentManager.setProjectExpanded", { projectId: id, expanded: false }), deps)
+
+    const restored = new ProjectRegistry(storage)
+    expect(restored.expanded(id)).toBe(false)
+    expect(registry.list()).toEqual([])
+  })
+
   it("does not initialize untrusted projects on expand", async () => {
     const repo = gitRepo()
     const { deps, registry, calls } = setup()
diff --git a/packages/kilo-vscode/tests/unit/agent-project-progress.test.ts b/packages/kilo-vscode/tests/unit/agent-project-progress.test.ts
new file mode 100644
index 00000000000..0caddba5c5f
--- /dev/null
+++ b/packages/kilo-vscode/tests/unit/agent-project-progress.test.ts
@@ -0,0 +1,59 @@
+import { describe, expect, it } from "bun:test"
+import { createProjectStore } from "../../webview-ui/agent-manager/project/store"
+import { clearMultiVersionBusy, markMultiVersionBusy } from "../../webview-ui/agent-manager/project/progress"
+
+const state = (projectId: string) => ({
+  type: "agentManager.state" as const,
+  projectId,
+  worktrees: [
+    {
+      id: "same",
+      branch: `${projectId}-same`,
+      path: `/repo/${projectId}/same`,
+      parentBranch: "main",
+      createdAt: "2026-01-01",
+      groupId: "group",
+    },
+  ],
+  sessions: [{ id: `${projectId}-session`, worktreeId: "same", createdAt: "2026-01-01" }],
+  sections: [],
+})
+
+describe("multi-project progress state", () => {
+  it("updates only the owning project's grouped worktrees", () => {
+    const first = createProjectStore("a")
+    const second = createProjectStore("b")
+    first.applyState(state("a"))
+    second.applyState(state("b"))
+    first.setBusy(new Map([["same", { reason: "setting-up" as const }]]))
+    second.setBusy(new Map([["same", { reason: "setting-up" as const }]]))
+
+    clearMultiVersionBusy(second, "group")
+
+    expect(first.busy().has("same")).toBe(true)
+    expect(second.busy().has("same")).toBe(false)
+
+    second.setBusy(new Map([["same", { reason: "deleting" as const }]]))
+    clearMultiVersionBusy(second, "group")
+    expect(second.busy().get("same")?.reason).toBe("deleting")
+  })
+
+  it("marks a newly created grouped worktree as busy in its project store", () => {
+    const store = createProjectStore("a")
+    store.applyState(state("a"))
+
+    markMultiVersionBusy(store, "a-session")
+
+    expect(store.busy().get("same")?.reason).toBe("setting-up")
+  })
+
+  it("does not replace deletion progress when marking a grouped worktree", () => {
+    const store = createProjectStore("a")
+    store.applyState(state("a"))
+    store.setBusy(new Map([["same", { reason: "deleting" as const }]]))
+
+    markMultiVersionBusy(store, "a-session")
+
+    expect(store.busy().get("same")?.reason).toBe("deleting")
+  })
+})
diff --git a/packages/kilo-vscode/tests/unit/git-ops.test.ts b/packages/kilo-vscode/tests/unit/git-ops.test.ts
index bd56efa8274..563620705d5 100644
--- a/packages/kilo-vscode/tests/unit/git-ops.test.ts
+++ b/packages/kilo-vscode/tests/unit/git-ops.test.ts
@@ -58,6 +58,23 @@ describe("GitOps", () => {
     })
   })
 
+  describe("root", () => {
+    it("resolves the nearest enclosing repository", async () => {
+      const git = ops(async (args) => {
+        if (args[0] === "rev-parse" && args[1] === "--show-toplevel") return "/workspace/frontend"
+        return ""
+      })
+      expect(await git.root("/workspace/frontend/src")).toBe("/workspace/frontend")
+    })
+
+    it("returns undefined outside a repository", async () => {
+      const git = ops(async () => {
+        throw new Error("not a git repo")
+      })
+      expect(await git.root("/workspace")).toBeUndefined()
+    })
+  })
+
   describe("resolveRemote", () => {
     it("uses upstream remote when upstream is configured", async () => {
       const git = ops(async (args) => {
diff --git a/packages/kilo-vscode/tests/unit/kilo-provider-followup.test.ts b/packages/kilo-vscode/tests/unit/kilo-provider-followup.test.ts
index 1965da54521..29be0ad5b20 100644
--- a/packages/kilo-vscode/tests/unit/kilo-provider-followup.test.ts
+++ b/packages/kilo-vscode/tests/unit/kilo-provider-followup.test.ts
@@ -8,8 +8,12 @@ type Internals = {
   webview: { postMessage: (message: unknown) => Promise<unknown> } | null
   trackedSessionIds: Set<string>
   currentSession: Session | null
+  projectID: string | undefined
+  isWebviewReady: boolean
   pendingFollowup: { dir: string; time: number } | null
   handleLoadMessages: (sessionID: string) => Promise<void>
+  handleEvent: (event: Event, directory?: string) => void
+  refreshGitStatus: (directory?: string) => Promise<void>
   initializeConnection: () => Promise<void>
   syncWebviewState: () => Promise<void>
   flushPendingSessionRefresh: () => Promise<void>
@@ -43,6 +47,18 @@ function created(input: { id: string; directory: string; parentID?: string }): E
   } as Event
 }
 
+function info(input: { id: string; projectID: string; directory: string }): Session {
+  return {
+    id: input.id,
+    slug: `${input.id}-slug`,
+    projectID: input.projectID,
+    directory: input.directory,
+    title: "Session",
+    version: "1",
+    time: { created: 1, updated: 1 },
+  }
+}
+
 function connection() {
   let filter: ((event: Event) => boolean) | undefined
   let listener: ((event: Event) => void) | undefined
@@ -80,6 +96,135 @@ function connection() {
 }
 
 describe("KiloProvider follow-up sessions", () => {
+  it("scopes shared session events to the active project directory", () => {
+    const service = connection()
+    const provider = new KiloProvider({} as never, service as never, undefined, {
+      rootDirectory: () => "/repo/project-b",
+      projectQualifier: () => ({ projectId: "project-b" }),
+    })
+    const internal = provider as unknown as Internals
+    const sent: unknown[] = []
+    const sharedID = "ses-shared"
+
+    internal.webview = {
+      postMessage: async (message: unknown) => {
+        sent.push(message)
+        return true
+      },
+    }
+    internal.isWebviewReady = true
+    internal.currentSession = info({ id: sharedID, projectID: "backend-project-b", directory: "/repo/project-b" })
+    internal.projectID = "backend-project-a"
+    internal.trackedSessionIds.add(sharedID)
+
+    // A background project's event must not overwrite the active project's
+    // transcript when both instances expose the same raw session key.
+    internal.handleEvent(
+      {
+        type: "message.updated",
+        properties: {
+          sessionID: sharedID,
+          info: {
+            id: "msg-project-a",
+            sessionID: sharedID,
+            role: "assistant",
+            time: { created: 1 },
+          },
+        },
+      } as Event,
+      "/repo/project-a",
+    )
+    expect(sent).toEqual([])
+
+    // Switching projects can briefly leave the backend project identity stale;
+    // the active directory is the authoritative scope during that transition.
+    internal.handleEvent(
+      {
+        type: "session.created",
+        properties: { sessionID: sharedID, info: internal.currentSession },
+      } as Event,
+      "/repo/project-b",
+    )
+    expect(sent).toContainEqual({
+      type: "sessionCreated",
+      session: {
+        id: sharedID,
+        title: "Session",
+        createdAt: new Date(1).toISOString(),
+        updatedAt: new Date(1).toISOString(),
+        parentID: null,
+        revert: null,
+        summary: null,
+      },
+    })
+  })
+
+  it("refreshes Git from the file path in a completed edit tool part", () => {
+    const service = connection()
+    const provider = new KiloProvider({} as never, service as never, undefined, {
+      rootDirectory: () => "/workspace",
+      projectQualifier: () => ({ projectId: "workspace" }),
+    })
+    const internal = provider as unknown as Internals
+    const dirs: string[] = []
+    const sessionID = "ses-edit"
+    internal.currentSession = info({ id: sessionID, projectID: "backend-workspace", directory: "/workspace" })
+    internal.trackedSessionIds.add(sessionID)
+    internal.refreshGitStatus = async (directory) => {
+      if (directory) dirs.push(directory)
+    }
+
+    internal.handleEvent(
+      {
+        type: "message.part.updated",
+        properties: {
+          sessionID,
+          part: {
+            type: "tool",
+            state: { status: "completed" },
+            metadata: { filepath: "/workspace/frontend/src/app.ts" },
+          },
+        },
+      } as Event,
+      "/workspace",
+    )
+
+    expect(dirs).toEqual(["/workspace/frontend/src"])
+  })
+
+  it("ignores completed tool paths outside the active project", () => {
+    const service = connection()
+    const provider = new KiloProvider({} as never, service as never, undefined, {
+      rootDirectory: () => "/workspace",
+      projectQualifier: () => ({ projectId: "workspace" }),
+    })
+    const internal = provider as unknown as Internals
+    const dirs: string[] = []
+    const sessionID = "ses-external-edit"
+    internal.currentSession = info({ id: sessionID, projectID: "backend-workspace", directory: "/workspace" })
+    internal.trackedSessionIds.add(sessionID)
+    internal.refreshGitStatus = async (directory) => {
+      if (directory) dirs.push(directory)
+    }
+
+    internal.handleEvent(
+      {
+        type: "message.part.updated",
+        properties: {
+          sessionID,
+          part: {
+            type: "tool",
+            state: { status: "completed" },
+            metadata: { filepath: "/other-repo/src/app.ts" },
+          },
+        },
+      } as Event,
+      "/workspace",
+    )
+
+    expect(dirs).toEqual([])
+  })
+
   it("ignores subagents before adopting pending follow-up sessions", async () => {
     const service = connection()
     const provider = new KiloProvider({} as never, service as never)
diff --git a/packages/kilo-vscode/tests/unit/kilo-provider-route-integration.test.ts b/packages/kilo-vscode/tests/unit/kilo-provider-route-integration.test.ts
index b8053f7abe3..475607e5fdd 100644
--- a/packages/kilo-vscode/tests/unit/kilo-provider-route-integration.test.ts
+++ b/packages/kilo-vscode/tests/unit/kilo-provider-route-integration.test.ts
@@ -1,4 +1,7 @@
 import { describe, it, expect } from "bun:test"
+import * as fs from "fs/promises"
+import * as os from "os"
+import * as path from "path"
 import { ProjectRouteService } from "../../src/agent-manager/project/route"
 
 // vscode mock is provided by the shared preload (tests/setup/vscode-mock.ts)
@@ -11,8 +14,9 @@ type SessionGetParams = { sessionID: string; directory: string }
  * session.get records every call so tests can assert which directory was
  * queried. Mirrors the shape used by kilo-provider-session-refresh.test.ts.
  */
-function mockConnection(getImpl?: (p: SessionGetParams) => Promise<unknown>) {
+function mockConnection(getImpl?: (p: SessionGetParams) => Promise<unknown>, vcs = "git") {
   const calls: SessionGetParams[] = []
+  const projectCalls: string[] = []
   const client = {
     session: {
       get: async (p: SessionGetParams) => {
@@ -32,6 +36,12 @@ function mockConnection(getImpl?: (p: SessionGetParams) => Promise<unknown>) {
       },
       list: async () => ({ data: [] }),
     },
+    project: {
+      current: async (p: { directory: string }) => {
+        projectCalls.push(p.directory)
+        return { data: { vcs } }
+      },
+    },
     provider: { list: async () => ({ data: { all: [], connected: {}, default: {} } }) },
     app: {
       agents: async () => ({ data: [] }),
@@ -47,6 +57,7 @@ function mockConnection(getImpl?: (p: SessionGetParams) => Promise<unknown>) {
   let current: typeof client | null = client
   return {
     calls,
+    projectCalls,
     connection: {
       connect: async () => {
         current = client
@@ -77,11 +88,27 @@ function mockConnection(getImpl?: (p: SessionGetParams) => Promise<unknown>) {
   }
 }
 
+async function withNestedRepo(run: (root: string) => Promise<void>): Promise<void> {
+  const base = await fs.mkdtemp(path.join(os.tmpdir(), "kilo-nested-repo-"))
+  const root = path.join(base, "frontend")
+  await fs.mkdir(root)
+  const result = Bun.spawnSync({ cmd: ["git", "init"], cwd: root, stdout: "pipe", stderr: "pipe" })
+  if (result.exitCode !== 0) throw new Error(Buffer.from(result.stderr).toString())
+  try {
+    await run(root)
+  } finally {
+    await fs.rm(base, { recursive: true, force: true })
+  }
+}
+
 type ProviderInternals = {
   client: unknown
   connectionState: "connecting" | "connected" | "disconnected" | "error"
   initConnectionPromise: Promise<void> | null
+  isWebviewReady: boolean
   webview: { postMessage: (message: unknown) => Promise<unknown> } | null
+  startStatsPolling: () => void
+  refreshGitStatus: (directory?: string) => Promise<void>
   handleSendCommand: (
     command: string,
     args: string,
@@ -111,6 +138,49 @@ function connect(internal: ProviderInternals): void {
 }
 
 describe("KiloProvider route integration", () => {
+  it("finds a nested Git root when the workspace parent is not a repo", async () => {
+    await withNestedRepo(async (root) => {
+      const source = path.join(root, "src")
+      await fs.mkdir(source)
+      const { connection, projectCalls } = mockConnection(undefined, "none")
+      const provider = new KiloProvider({} as never, connection, undefined, {
+        rootDirectory: () => source,
+      })
+      const internal = provider as unknown as ProviderInternals
+      const sent: unknown[] = []
+      internal.connectionState = "connected"
+      internal.initConnectionPromise = Promise.resolve()
+      internal.isWebviewReady = true
+      internal.startStatsPolling = () => {}
+      internal.webview = { postMessage: async (message) => sent.push(message) }
+
+      await internal.refreshGitStatus(source)
+
+      expect(projectCalls).toEqual([source])
+      expect(sent).toContainEqual({ type: "gitStatus", repo: true })
+    })
+  })
+
+  it("checks Git capability in the active project directory", async () => {
+    const { connection, projectCalls } = mockConnection()
+    const provider = new KiloProvider({} as never, connection, undefined, {
+      rootDirectory: () => "/workspace/parent/project-b",
+      projectQualifier: () => ({ projectId: "project-b" }),
+    })
+    const internal = provider as unknown as ProviderInternals
+    const sent: unknown[] = []
+    internal.connectionState = "connected"
+    internal.initConnectionPromise = Promise.resolve()
+    internal.isWebviewReady = true
+    internal.startStatsPolling = () => {}
+    internal.webview = { postMessage: async (message) => sent.push(message) }
+
+    await internal.refreshGitStatus()
+
+    expect(projectCalls).toEqual(["/workspace/parent/project-b"])
+    expect(sent).toContainEqual({ type: "gitStatus", repo: true })
+  })
+
   it("resolves a unique Local session route to its exact project root", async () => {
     const routes = new ProjectRouteService()
     routes.registerProject("a", "/repo/a", 1)
diff --git a/packages/kilo-vscode/tests/unit/kilo-provider-session-refresh.test.ts b/packages/kilo-vscode/tests/unit/kilo-provider-session-refresh.test.ts
index 3cb7d11ed69..e96a67d6b71 100644
--- a/packages/kilo-vscode/tests/unit/kilo-provider-session-refresh.test.ts
+++ b/packages/kilo-vscode/tests/unit/kilo-provider-session-refresh.test.ts
@@ -9,11 +9,20 @@ type State = "connecting" | "connected" | "disconnected" | "error"
 type ProviderInternals = {
   connectionState: State
   pendingSessionRefresh: boolean
+  projectID: string | undefined
   webview: { postMessage: (message: unknown) => Promise<unknown> } | null
   initializeConnection: () => Promise<void>
   handleLoadSessions: () => Promise<void>
 }
 
+function deferred<T>() {
+  let resolve: (value: T) => void = () => {}
+  const promise = new Promise<T>((done) => {
+    resolve = done
+  })
+  return { promise, resolve }
+}
+
 function createContext(overrides?: Partial<SessionRefreshContext>): SessionRefreshContext & { sent: unknown[] } {
   const sent: unknown[] = []
   return {
@@ -100,6 +109,40 @@ function createConnection(client: ReturnType<typeof createClient>) {
 }
 
 describe("KiloProvider pending session refresh", () => {
+  it("does not let a late listing restore the previous project's identity", async () => {
+    const client = createClient()
+    const pending = new Map<string, ReturnType<typeof deferred<{ data: unknown[] }>>>()
+    client.session.list = async (params: { directory: string }) => {
+      const next = deferred<{ data: unknown[] }>()
+      pending.set(params.directory, next)
+      return next.promise as never
+    }
+    const connection = createConnection(client)
+    await connection.connect()
+    let active = "a"
+    const provider = new KiloProvider({} as never, connection as never, undefined, {
+      rootDirectory: () => `/repo/${active}`,
+      projectQualifier: () => ({ projectId: active }),
+    })
+    const internal = provider as unknown as ProviderInternals
+    internal.connectionState = "connected"
+
+    const first = internal.handleLoadSessions()
+    active = "b"
+    const second = internal.handleLoadSessions()
+
+    pending.get("/repo/b")!.resolve({
+      data: [{ id: "ses-b", projectID: "backend-b", time: { created: 1, updated: 1 } }],
+    })
+    await second
+    pending.get("/repo/a")!.resolve({
+      data: [{ id: "ses-a", projectID: "backend-a", time: { created: 1, updated: 1 } }],
+    })
+    await first
+
+    expect(internal.projectID).toBe("backend-b")
+  })
+
   it("keeps worktree sessions with legacy project ids", async () => {
     const sent: unknown[] = []
     const ctx = createContext({
diff --git a/packages/kilo-vscode/tests/unit/navigate.test.ts b/packages/kilo-vscode/tests/unit/navigate.test.ts
index be6e5d816e1..3f23206ec69 100644
--- a/packages/kilo-vscode/tests/unit/navigate.test.ts
+++ b/packages/kilo-vscode/tests/unit/navigate.test.ts
@@ -401,7 +401,7 @@ describe("buildProjectNavOrder", () => {
     expect(order.map((e) => e.id)).toEqual([localNavId("A"), worktreeNavId("A", "aw2")])
   })
 
-  it("renders section members before ungrouped worktrees (matching the project body)", () => {
+  it("renders ungrouped worktrees before section members (matching the project body)", () => {
     const order = buildProjectNavOrder([
       project({
         id: "A",
@@ -411,7 +411,76 @@ describe("buildProjectNavOrder", () => {
         unassigned: [],
       }),
     ])
-    expect(order.map((e) => e.id)).toEqual([localNavId("A"), worktreeNavId("A", "aw1"), worktreeNavId("A", "aw2")])
+    expect(order.map((e) => e.id)).toEqual([localNavId("A"), worktreeNavId("A", "aw2"), worktreeNavId("A", "aw1")])
+  })
+
+  it("follows persisted top-level section order and worktree order", () => {
+    const order = buildProjectNavOrder([
+      project({
+        id: "A",
+        expanded: true,
+        worktrees: [{ id: "aw1", sectionId: "s1" }, { id: "aw2" }, { id: "aw3", sectionId: "s2" }],
+        worktreeOrder: ["aw2", "s2", "s1", "aw3", "aw1"],
+        sections: [
+          { id: "s1", collapsed: false },
+          { id: "s2", collapsed: false },
+        ],
+        unassigned: [],
+      }),
+    ])
+
+    expect(order.map((e) => e.id)).toEqual([
+      localNavId("A"),
+      worktreeNavId("A", "aw2"),
+      worktreeNavId("A", "aw3"),
+      worktreeNavId("A", "aw1"),
+    ])
+  })
+
+  it("keeps multi-version worktrees adjacent", () => {
+    const order = buildProjectNavOrder([
+      project({
+        id: "A",
+        expanded: true,
+        worktrees: [{ id: "aw1", groupId: "g" }, { id: "aw2" }, { id: "aw3", groupId: "g" }],
+        worktreeOrder: ["aw1", "aw2", "aw3"],
+        sections: [],
+        unassigned: [],
+      }),
+    ])
+
+    expect(order.map((e) => e.id)).toEqual([
+      localNavId("A"),
+      worktreeNavId("A", "aw1"),
+      worktreeNavId("A", "aw3"),
+      worktreeNavId("A", "aw2"),
+    ])
+  })
+
+  it("matches raw ungrouped order when sections are present", () => {
+    const order = buildProjectNavOrder([
+      project({
+        id: "A",
+        expanded: true,
+        worktrees: [
+          { id: "aw1", groupId: "g" },
+          { id: "aw2" },
+          { id: "aw3", groupId: "g" },
+          { id: "aw4", sectionId: "s1" },
+        ],
+        worktreeOrder: ["aw1", "aw2", "aw3", "s1", "aw4"],
+        sections: [{ id: "s1", collapsed: false }],
+        unassigned: [],
+      }),
+    ])
+
+    expect(order.map((e) => e.id)).toEqual([
+      localNavId("A"),
+      worktreeNavId("A", "aw1"),
+      worktreeNavId("A", "aw2"),
+      worktreeNavId("A", "aw3"),
+      worktreeNavId("A", "aw4"),
+    ])
   })
 
   it("excludes unassigned sessions when the sessions section is collapsed", () => {
diff --git a/packages/kilo-vscode/tests/unit/project-local-navigation.test.ts b/packages/kilo-vscode/tests/unit/project-local-navigation.test.ts
new file mode 100644
index 00000000000..7f5247b181d
--- /dev/null
+++ b/packages/kilo-vscode/tests/unit/project-local-navigation.test.ts
@@ -0,0 +1,66 @@
+import { describe, expect, it } from "bun:test"
+import { worktreeNavId } from "../../webview-ui/agent-manager/navigate"
+import { projectAdjacentHint, projectWorktreeRow } from "../../webview-ui/agent-manager/project-local-navigation"
+
+describe("projectAdjacentHint", () => {
+  it("does not leak a hint to another project with the same raw ID", () => {
+    expect(projectAdjacentHint("project-a", "project-a", "shared", "local", ["local", "shared"], "prev", "next")).toBe(
+      "next",
+    )
+    expect(projectAdjacentHint("project-b", "project-a", "shared", "local", ["local", "shared"], "prev", "next")).toBe(
+      "",
+    )
+  })
+
+  it("uses the active project's local sidebar order", () => {
+    expect(projectAdjacentHint("project-a", "project-a", "shared", "local", ["local", "shared"], "prev", "next")).toBe(
+      "next",
+    )
+    expect(projectAdjacentHint("project-a", "project-a", "local", "shared", ["local", "shared"], "prev", "next")).toBe(
+      "prev",
+    )
+    expect(
+      projectAdjacentHint("project-b", "project-b", "shared", "local", ["local", "other", "shared"], "prev", "next"),
+    ).toBe("")
+  })
+
+  it("keeps shortcut and worktree keybinding values scoped for duplicate raw IDs", () => {
+    const bindings = {
+      previousSession: "Ctrl+Alt+Up",
+      nextSession: "Ctrl+Alt+Down",
+      closeWorktree: "Ctrl+Shift+W",
+      openWorktree: "Ctrl+Shift+O",
+    }
+    const shortcuts = new Map([
+      [worktreeNavId("project-a", "shared"), 2],
+      [worktreeNavId("project-b", "shared"), 4],
+    ])
+    const first = projectWorktreeRow({
+      projectId: "project-a",
+      activeProjectId: "project-a",
+      worktreeId: "shared",
+      activeId: "local",
+      flatIds: ["local", "shared"],
+      bindings,
+      shortcuts,
+    })
+    const second = projectWorktreeRow({
+      projectId: "project-b",
+      activeProjectId: "project-a",
+      worktreeId: "shared",
+      activeId: "local",
+      flatIds: ["local", "shared"],
+      bindings,
+      shortcuts,
+    })
+
+    expect(first.navHint).toBe(bindings.nextSession)
+    expect(second.navHint).toBe("")
+    expect(first.shortcut).toBe(2)
+    expect(second.shortcut).toBe(4)
+    expect(first.closeKeybind).toBe(bindings.closeWorktree)
+    expect(first.openKeybind).toBe(bindings.openWorktree)
+    expect(second.closeKeybind).toBe(bindings.closeWorktree)
+    expect(second.openKeybind).toBe(bindings.openWorktree)
+  })
+})
diff --git a/packages/kilo-vscode/tests/unit/project-store.test.ts b/packages/kilo-vscode/tests/unit/project-store.test.ts
index 84dbe9e710c..7f0c7d070e5 100644
--- a/packages/kilo-vscode/tests/unit/project-store.test.ts
+++ b/packages/kilo-vscode/tests/unit/project-store.test.ts
@@ -42,4 +42,16 @@ describe("project stores", () => {
       same: { worktreeId: "same", state: "running" },
     })
   })
+
+  it("keeps busy worktrees isolated between projects", () => {
+    const first = createProjectStore("a")
+    const second = createProjectStore("b")
+    first.applyState(state("a", ["same"]))
+    second.applyState(state("b", ["same"]))
+
+    first.setBusy(new Map([["same", { reason: "setting-up" as const }]]))
+
+    expect(first.busy().has("same")).toBe(true)
+    expect(second.busy().has("same")).toBe(false)
+  })
 })
diff --git a/packages/kilo-vscode/tests/unit/server-manager-utils.test.ts b/packages/kilo-vscode/tests/unit/server-manager-utils.test.ts
index db9ac71a419..ac811c0532b 100644
--- a/packages/kilo-vscode/tests/unit/server-manager-utils.test.ts
+++ b/packages/kilo-vscode/tests/unit/server-manager-utils.test.ts
@@ -315,10 +315,17 @@ describe("server workspace helpers", () => {
     expect(resolveIndexingEnv([{ uri: { fsPath: "/repo" } }])).toEqual({})
   })
 
-  it("uses the shared database for the managed backend while preserving the environment", () => {
-    expect(resolveManagedServerEnv({ PATH: "/usr/bin", KILO_DISABLE_CHANNEL_DB: "false" })).toEqual({
+  it("disables unused managed-backend services while preserving the environment", () => {
+    expect(
+      resolveManagedServerEnv({
+        PATH: "/usr/bin",
+        KILO_DISABLE_CHANNEL_DB: "false",
+        KILO_EXPERIMENTAL_DISABLE_FILEWATCHER: "false",
+      }),
+    ).toEqual({
       PATH: "/usr/bin",
       KILO_DISABLE_CHANNEL_DB: "true",
+      KILO_EXPERIMENTAL_DISABLE_FILEWATCHER: "true",
     })
   })
 })
diff --git a/packages/kilo-vscode/tests/unit/speech-to-text-availability.test.ts b/packages/kilo-vscode/tests/unit/speech-to-text-availability.test.ts
index 83848168963..1361f8f5166 100644
--- a/packages/kilo-vscode/tests/unit/speech-to-text-availability.test.ts
+++ b/packages/kilo-vscode/tests/unit/speech-to-text-availability.test.ts
@@ -23,9 +23,11 @@ describe("speech-to-text availability", () => {
   })
 
   it("normalizes configured and unknown transcription models", () => {
-    expect(selectedSpeechToTextModel({ experimental: { speech_to_text_model: "google/chirp-3" } })).toBe(
-      "google/chirp-3",
-    )
+    expect(
+      selectedSpeechToTextModel({ experimental: { speech_to_text_model: "google/chirp-3" } }, [
+        { id: "google/chirp-3", label: "Chirp 3", provider: "Google" },
+      ]),
+    ).toBe("google/chirp-3")
     expect(selectedSpeechToTextModel({ experimental: { speech_to_text_model: "unknown/model" } })).toBe(
       DEFAULT_SPEECH_TO_TEXT_MODEL.id,
     )
diff --git a/packages/kilo-vscode/tests/unit/speech-to-text-catalog.test.ts b/packages/kilo-vscode/tests/unit/speech-to-text-catalog.test.ts
new file mode 100644
index 00000000000..a4e0a8029f8
--- /dev/null
+++ b/packages/kilo-vscode/tests/unit/speech-to-text-catalog.test.ts
@@ -0,0 +1,38 @@
+import { describe, expect, it } from "bun:test"
+import { parseSpeechToTextCatalog } from "../../src/speech-to-text/catalog"
+import { DEFAULT_SPEECH_TO_TEXT_MODEL } from "../../src/speech-to-text/models"
+
+describe("speech-to-text discovery", () => {
+  it("keeps transcription catalog metadata authoritative and exposes additions", () => {
+    const models = parseSpeechToTextCatalog([
+      {
+        id: "fish-audio/transcribe-1",
+        name: "Fish Audio: Transcribe 1",
+      },
+      {
+        id: "openai/gpt-4o-mini-transcribe",
+        name: "OpenAI: GPT-4o Mini Transcribe",
+      },
+      {
+        id: "openai/whisper-1",
+        name: "Whisper 1",
+      },
+    ])
+
+    expect(models).toEqual([
+      { id: "fish-audio/transcribe-1", label: "Transcribe 1", provider: "Fish Audio" },
+      {
+        id: "openai/gpt-4o-mini-transcribe",
+        label: "GPT-4o Mini Transcribe",
+        provider: "OpenAI",
+      },
+      { id: "openai/whisper-1", label: "Whisper 1", provider: "openai" },
+    ])
+  })
+
+  it("rejects empty or malformed catalogs so callers can use the static fallback", () => {
+    expect(parseSpeechToTextCatalog([])).toBeUndefined()
+    expect(parseSpeechToTextCatalog({ data: [] })).toBeUndefined()
+    expect(DEFAULT_SPEECH_TO_TEXT_MODEL.id).toBe("openai/whisper-large-v3-turbo")
+  })
+})
diff --git a/packages/kilo-vscode/webview-ui/agent-manager/AgentManagerApp.tsx b/packages/kilo-vscode/webview-ui/agent-manager/AgentManagerApp.tsx
index 939a8e505be..c2a0dcdfda5 100644
--- a/packages/kilo-vscode/webview-ui/agent-manager/AgentManagerApp.tsx
+++ b/packages/kilo-vscode/webview-ui/agent-manager/AgentManagerApp.tsx
@@ -89,6 +89,7 @@ import type { WorktreeBusyState } from "./project/store"
 import { rememberTarget, restoreProjectTarget } from "./project/restore"
 import { createProjectStateRouter } from "./project/state"
 import { applyRunStatus } from "./project/run-status"
+import { clearMultiVersionBusy, markMultiVersionBusy } from "./project/progress"
 import { selectLocalAction, selectWorktreeAction } from "./selection-actions"
 import { DataBridge } from "../src/App"
 import { LanguageBridge } from "../src/context/language-bridge"
@@ -103,7 +104,7 @@ import {
   focusChatSearch,
   LOCAL,
 } from "./navigate"
-import { createProjectNav } from "./project-nav"
+import { buildProjectNavEntries, createProjectNav } from "./project-nav"
 import {
   addPendingTab as addLocalPendingTab,
   nextTabAfterClose,
@@ -173,6 +174,7 @@ import { createMarkdownRender } from "./review-preferences"
 import { createSidebarCollapse } from "./sidebar-collapse"
 import { SidebarToggleButton } from "./SidebarToggleButton"
 import { setTabWidths } from "./tab-widths"
+import { clampPanelWidth, maxPanelWidth, minPanelWidth } from "./side-panel-layout"
 import { buildShortcutCategories } from "./shortcuts"
 import { tracker } from "./telemetry"
 import { createChatFocus, hasQuestionOption } from "./focus"
@@ -273,7 +275,7 @@ const AgentManagerContent: Component = () => {
   const MAX_SIDEBAR_WIDTH_RATIO = 0.4
 
   // Recover persisted local session IDs from webview state
-  const persisted = vscode.getState<PersistedProjectTabs & { sidebarWidth?: number }>()
+  const persisted = vscode.getState<PersistedProjectTabs & { sidebarWidth?: number; sidePanelWidth?: number }>()
   const registry = createProjectRegistry({
     persisted: persisted ?? {},
     activeId: () => currentProjectId() ?? "single",
@@ -313,26 +315,15 @@ const AgentManagerContent: Component = () => {
   const diffLoading = diffs.diffLoading
   const setDiffLoading = diffs.setDiffLoading
   const diffNotices = diffs.diffNotices
-  // The diff and terminal panels each remember their own width: a diff
-  // benefits from half the window, a terminal only needs about a third.
-  const TERMINAL_MIN_WIDTH = 360
-  const TERMINAL_MAX_WIDTH = 640
-  const [diffWidth, setDiffWidth] = createSignal(Math.round(window.innerWidth * 0.5))
-  const [terminalWidth, setTerminalWidth] = createSignal(
-    Math.min(TERMINAL_MAX_WIDTH, Math.max(TERMINAL_MIN_WIDTH, Math.round(window.innerWidth / 3))),
-  )
-  // The hidden-but-mounted host still fits the terminal, so pick the
-  // terminal's width whenever one is alive and no other mode is showing.
-  const widthMode = () => sidePanel() ?? (terms.sides().length > 0 ? "terminal" : null)
-  const hostWidth = () => (widthMode() === "terminal" ? terminalWidth() : diffWidth())
-  const sideMin = () => (widthMode() === "terminal" ? TERMINAL_MIN_WIDTH : 200)
+  // Diff and terminal views share one inspector width, restored from webview
+  // state so the user's divider position survives panel reloads.
+  const [panelWidth, setPanelWidth] = createSignal(clampPanelWidth(persisted?.sidePanelWidth, window.innerWidth))
   const resizeSide = (width: number) => {
-    pendingSideWidth = Math.max(sideMin(), Math.min(width, window.innerWidth * 0.8))
+    pendingSideWidth = clampPanelWidth(width, window.innerWidth)
     if (sideRaf !== undefined) return
     sideRaf = requestAnimationFrame(() => {
       sideRaf = undefined
-      if (widthMode() === "terminal") setTerminalWidth(pendingSideWidth!)
-      else setDiffWidth(pendingSideWidth!)
+      setPanelWidth(pendingSideWidth!)
     })
   }
   const showSideTerminal = () => {
@@ -642,6 +633,7 @@ const AgentManagerContent: Component = () => {
     },
     key: () => registry.active().id,
     width: sidebarWidth,
+    panelWidth,
     get: () => vscode.getState<Record<string, unknown>>(),
     set: (value) => vscode.setState(value),
   })
@@ -865,6 +857,16 @@ const AgentManagerContent: Component = () => {
   /** True when a local session is actively working. */
   const isLocalBusy = (): boolean => isAnySessionBusy(localSessionIDs())
 
+  const projectBusy = (projectId: string, worktreeId: string | null): boolean => {
+    if (projectId === activeProjectId()) {
+      return worktreeId === null ? isLocalBusy() : isAgentBusy(worktreeId)
+    }
+    const ids = (projectSessionsLive()[projectId] ?? [])
+      .filter((item) => item.worktreeId === worktreeId)
+      .map((item) => item.id)
+    return isAnySessionBusy(ids)
+  }
+
   const isSessionBusy = (id: string): boolean => isAnySessionBusy([id])
 
   /** Worktrees sorted so that grouped items are always adjacent, respecting custom order if set. */
@@ -882,6 +884,11 @@ const AgentManagerContent: Component = () => {
   )
   /** Map from sidebar item id → 1-based shortcut number (⌘1 for LOCAL, ⌘2 for first worktree, etc.) */
   const shortcutMap = createMemo(() => buildShortcutMap(sidebarOrder()))
+  const projectShortcutMap = createMemo(() =>
+    buildShortcutMap(
+      buildProjectNavEntries(projectList(), projectStates(), projectLive.sessions()).map((entry) => ({ id: entry.id })),
+    ),
+  )
 
   const moveToSection = (ids: string[], sec: string | null) =>
     vscode.postMessage({ type: "agentManager.moveToSection", worktreeIds: ids, sectionId: sec })
@@ -1447,13 +1454,8 @@ const AgentManagerContent: Component = () => {
         const ev = msg as unknown as AgentManagerMultiVersionProgressMessage
         if (ev.status === "done" && ev.groupId) {
           // Clear busy state for all worktrees in this group
-          setBusyWorktrees((prev) => {
-            const next = new Map(prev)
-            for (const wt of worktrees()) {
-              if (wt.groupId === ev.groupId) next.delete(wt.id)
-            }
-            return next
-          })
+          const store = ev.projectId ? registry.ensure(ev.projectId) : registry.active()
+          clearMultiVersionBusy(store, ev.groupId)
         }
       }
 
@@ -1462,11 +1464,8 @@ const AgentManagerContent: Component = () => {
       if (msg.type === "agentManager.worktreeSetup") {
         const ev = msg as AgentManagerWorktreeSetupMessage
         if (ev.status === "ready" && ev.sessionId) {
-          const ms = managedSessions().find((s) => s.id === ev.sessionId)
-          const wt = ms?.worktreeId ? worktrees().find((w) => w.id === ms.worktreeId) : undefined
-          if (wt?.groupId) {
-            setBusyWorktrees((prev) => new Map([...prev, [wt.id, { reason: "setting-up" as const }]]))
-          }
+          const store = ev.projectId ? registry.ensure(ev.projectId) : registry.active()
+          markMultiVersionBusy(store, ev.sessionId)
         }
       }
 
@@ -1503,7 +1502,8 @@ const AgentManagerContent: Component = () => {
         // Clear busy state — use worktreeId from the message directly
         // to avoid race condition where managedSessions() hasn't updated yet
         if (ev.worktreeId) {
-          setBusyWorktrees((prev) => {
+          const store = ev.projectId ? registry.ensure(ev.projectId) : registry.active()
+          store.setBusy((prev) => {
             const next = new Map(prev)
             next.delete(ev.worktreeId)
             return next
@@ -2335,6 +2335,9 @@ const AgentManagerContent: Component = () => {
             projects={projectList()}
             states={projectStates()}
             store={(id) => registry.ensure(id)}
+            busy={(projectId, id) => registry.ensure(projectId).busy().has(id)}
+            working={(projectId, id) => projectBusy(projectId, id)}
+            localBusy={(projectId) => projectBusy(projectId, null)}
             stats={projectLive.stats()}
             local={projectLive.local()}
             prs={projectLive.prs()}
@@ -2347,6 +2350,7 @@ const AgentManagerContent: Component = () => {
             t={t}
             onSearchRef={(ref) => (sidebarSearchMenu = ref)}
             onShortcuts={handleShowKeyboardShortcuts}
+            shortcutMap={projectShortcutMap}
           />
         </Show>
         <Show when={!multiProject()}>
@@ -2459,20 +2463,6 @@ const AgentManagerContent: Component = () => {
           track={metrics.click}
         />
 
-        {/* Empty worktree state */}
-        <Show when={contextEmpty()}>
-          <div class="am-empty-state">
-            <div class="am-empty-state-icon">
-              <Icon name="branch" size="large" />
-            </div>
-            <div class="am-empty-state-text">{t("agentManager.session.noSessions")}</div>
-            <Button variant="primary" size="small" onClick={handleAddSession}>
-              {t("agentManager.session.new")}
-              <span class="am-shortcut-hint">{kb().newTab ?? ""}</span>
-            </Button>
-          </div>
-        </Show>
-
         <Show when={overlay()}>
           {(state) => (
             <div class="am-setup-overlay">
@@ -2637,16 +2627,16 @@ const AgentManagerContent: Component = () => {
               <Show when={sidePanel() !== null || terms.sides().length > 0}>
                 <div
                   class={`am-diff-resize ${sidePanel() === null ? "am-side-host-hidden" : ""}`}
-                  style={{ width: `${hostWidth()}px` }}
+                  style={{ width: `${panelWidth()}px` }}
                   inert={sidePanel() === null}
                 >
                   <Show when={sidePanel() !== null}>
                     <ResizeHandle
                       direction="horizontal"
                       edge="start"
-                      size={hostWidth()}
-                      min={sideMin()}
-                      max={Math.round(window.innerWidth * 0.8)}
+                      size={panelWidth()}
+                      min={minPanelWidth(window.innerWidth)}
+                      max={maxPanelWidth(window.innerWidth)}
                       onResize={resizeSide}
                     />
                   </Show>
diff --git a/packages/kilo-vscode/webview-ui/agent-manager/DiffPanel.tsx b/packages/kilo-vscode/webview-ui/agent-manager/DiffPanel.tsx
index 083d892d557..ae15fa3cf6b 100644
--- a/packages/kilo-vscode/webview-ui/agent-manager/DiffPanel.tsx
+++ b/packages/kilo-vscode/webview-ui/agent-manager/DiffPanel.tsx
@@ -21,6 +21,7 @@ import { useProvider } from "../src/context/provider"
 import { useConfig } from "../src/context/config"
 import { canUseSpeechToText, selectedSpeechToTextModel } from "../src/components/speech-to-text/availability"
 import { useSpeechToText } from "../src/components/speech-to-text/useSpeechToText"
+import { useSpeechToTextModels } from "../src/context/speech-to-text-models"
 import {
   getDirectory,
   getFilename,
@@ -111,8 +112,9 @@ export const DiffPanel: Component<DiffPanelProps> = (props) => {
   const provider = useProvider()
   const { config } = useConfig()
   const speech = useSpeechToText(vscode, server, { t })
+  const speechModels = useSpeechToTextModels()
   const canUseSpeech = () => canUseSpeechToText(config(), provider.authStates())
-  const speechModel = () => selectedSpeechToTextModel(config())
+  const speechModel = () => selectedSpeechToTextModel(config(), speechModels.models())
   const isMac = typeof navigator !== "undefined" && /Mac|iPhone|iPad/.test(navigator.userAgent)
   const sendAllKeybind = () =>
     isMac ? t("agentManager.review.sendAllShortcut.mac") : t("agentManager.review.sendAllShortcut.other")
diff --git a/packages/kilo-vscode/webview-ui/agent-manager/NewWorktreeDialog.tsx b/packages/kilo-vscode/webview-ui/agent-manager/NewWorktreeDialog.tsx
index bdcba1c8453..72a68c57ef4 100644
--- a/packages/kilo-vscode/webview-ui/agent-manager/NewWorktreeDialog.tsx
+++ b/packages/kilo-vscode/webview-ui/agent-manager/NewWorktreeDialog.tsx
@@ -39,6 +39,7 @@ import {
 import { useLanguage } from "../src/context/language"
 import { useImageAttachments, type ImageAttachment } from "../src/hooks/useImageAttachments"
 import { useSpeechToText } from "../src/components/speech-to-text/useSpeechToText"
+import { useSpeechToTextModels } from "../src/context/speech-to-text-models"
 import { createSpeechShortcut } from "../src/components/speech-to-text/shortcut"
 import { convertToMentionPath } from "../src/utils/path-mentions"
 import { insertSpacedText } from "../src/components/chat/prompt-input-utils"
@@ -131,8 +132,9 @@ export const NewWorktreeDialog: Component<{
   const sandboxRequestID = crypto.randomUUID()
   const sandboxVisible = () => features().sandboxControls && globalConfig().sandbox?.enabled === true
   const speech = useSpeechToText(vscode, server, { t })
+  const speechModels = useSpeechToTextModels()
   const canUseSpeech = () => canUseSpeechToText(config(), provider.authStates())
-  const speechModel = () => selectedSpeechToTextModel(config())
+  const speechModel = () => selectedSpeechToTextModel(config(), speechModels.models())
   let prior: string | null = null
   let request: string | undefined
   const cancel = () => {
diff --git a/packages/kilo-vscode/webview-ui/agent-manager/ProjectList.tsx b/packages/kilo-vscode/webview-ui/agent-manager/ProjectList.tsx
index 3fb1220c166..1575e4e4074 100644
--- a/packages/kilo-vscode/webview-ui/agent-manager/ProjectList.tsx
+++ b/packages/kilo-vscode/webview-ui/agent-manager/ProjectList.tsx
@@ -34,11 +34,14 @@ interface Props {
   selection?: string
   currentSessionID?: () => string | undefined
   mode: ModeRouter
-  busy?: (id: string) => boolean
+  busy?: (projectId: string, id: string) => boolean
+  working?: (projectId: string, id: string) => boolean
+  localBusy?: (projectId: string) => boolean
   bindings: Record<string, string>
   t: LanguageContextValue["t"]
   onSearchRef: (ref: SidebarSearchMenuRef) => void
   onShortcuts: () => void
+  shortcutMap?: () => Map<string, number>
 }
 
 export const ProjectList: Component<Props> = (props) => {
@@ -211,12 +214,16 @@ export const ProjectList: Component<Props> = (props) => {
           project={project}
           state={props.states[project.id]}
           store={props.store?.(project.id)}
+          busy={(id) => props.busy?.(project.id, id) ?? false}
+          working={(id) => props.working?.(project.id, id) ?? false}
+          localBusy={() => props.localBusy?.(project.id) ?? false}
           stats={props.stats[project.id]}
           local={props.local[project.id]}
           prs={props.prs[project.id]}
           sessions={props.sessions[project.id]}
           selectedProject={props.selectedProject}
           selection={props.selection}
+          currentSessionID={props.currentSessionID}
           bindings={props.bindings}
           t={props.t}
           onSelectLocal={(projectId) => select({ projectId, kind: "local" })}
@@ -224,6 +231,7 @@ export const ProjectList: Component<Props> = (props) => {
           onSelectSession={(projectId, sessionId) => select({ projectId, kind: "session", sessionId })}
           onNewWorktree={newWorktree}
           onDefaultBranch={defaultBranch}
+          shortcutMap={props.shortcutMap}
         />
       )}
     />
diff --git a/packages/kilo-vscode/webview-ui/agent-manager/ProjectSidebarBody.tsx b/packages/kilo-vscode/webview-ui/agent-manager/ProjectSidebarBody.tsx
index 40b3cd82cb4..e3e2679321f 100644
--- a/packages/kilo-vscode/webview-ui/agent-manager/ProjectSidebarBody.tsx
+++ b/packages/kilo-vscode/webview-ui/agent-manager/ProjectSidebarBody.tsx
@@ -21,6 +21,7 @@ import type {
 import type { LanguageContextValue } from "../src/context/language"
 import { useVSCode } from "../src/context/vscode"
 import SectionHeader from "./SectionHeader"
+import { SidebarSectionHeader } from "./SidebarSectionHeader"
 import { WorktreeItem } from "./WorktreeItem"
 import { UnassignedSessionsSection } from "./UnassignedSessionsSection"
 import { ProjectActions } from "./ProjectActions"
@@ -30,18 +31,24 @@ import { sectionAwareDetector } from "./section-dnd"
 import { ConstrainDragXAxis } from "./constrain-drag-x"
 import { createProjectStore, type ProjectStore } from "./project/store"
 import { randomColor } from "./section-colors"
+import { projectSidebarOrder, projectWorktreeRow } from "./project-local-navigation"
+
+const isMac = typeof navigator !== "undefined" && /Mac|iPhone|iPad/.test(navigator.userAgent)
 
 interface Props {
   project: AgentProjectSnapshot
   state?: AgentManagerStateMessage
   store?: ProjectStore
   busy?: (id: string) => boolean
+  working?: (id: string) => boolean
+  localBusy?: () => boolean
   stats?: Record<string, WorktreeGitStats>
   local?: LocalGitStats
   prs?: Record<string, PRStatus | null>
   sessions?: ProjectSessionInfo[]
   selectedProject?: string
   selection?: string
+  currentSessionID?: () => string | undefined
   bindings: Record<string, string>
   t: LanguageContextValue["t"]
   onSelectLocal: (projectId: string) => void
@@ -49,6 +56,7 @@ interface Props {
   onSelectSession: (projectId: string, sessionId: string) => void
   onNewWorktree: (projectId: string) => void
   onDefaultBranch: (projectId: string, selected?: string, detected?: string) => void
+  shortcutMap?: () => Map<string, number>
 }
 
 /** Permanent real sidebar body for one expanded project. */
@@ -97,9 +105,23 @@ export const ProjectSidebarBody: Component<Props> = (props) => {
   const members = (sectionId: string) => sorted().filter((wt) => wt.sectionId === sectionId)
   const ungrouped = createMemo(() => sorted().filter((wt) => !wt.sectionId))
   const top = createMemo(() => buildTopLevelItems(sections(), ungrouped(), sorted(), order()))
+  const sidebarOrder = createMemo(() =>
+    projectSidebarOrder(top(), sorted(), sections(), members, state()?.sessionsCollapsed ? [] : localSessions()),
+  )
   const post = (message: Record<string, unknown>) =>
     vscode.postMessage({ ...message, projectId: props.project.id } as never)
 
+  const row = (id: string) =>
+    projectWorktreeRow({
+      projectId: props.project.id,
+      activeProjectId: props.selectedProject,
+      worktreeId: id,
+      activeId: props.selection ?? props.currentSessionID?.(),
+      flatIds: sidebarOrder(),
+      bindings: props.bindings,
+      shortcuts: props.shortcutMap?.(),
+    })
+
   const scope = (kind: "section" | "worktree", id: string) => `${props.project.id}:${kind}:${id}`
   const parse = (kind: "section" | "worktree", value: unknown) => {
     if (typeof value !== "string") return
@@ -207,6 +229,7 @@ export const ProjectSidebarBody: Component<Props> = (props) => {
   const renderWorktree = (worktree: WorktreeState, idx: () => number, list: WorktreeState[]) => {
     const label = () => firstOrderedTitle(sessions(worktree.id), store.tabOrder()[worktree.id], worktree.branch)
     const subtitle = () => (label() !== worktree.branch ? worktree.branch : undefined)
+    const values = () => row(worktree.id)
     const sortable = createSortable(scope("worktree", worktree.id))
     void sortable
     return (
@@ -219,9 +242,11 @@ export const ProjectSidebarBody: Component<Props> = (props) => {
           active={active() && props.selection === worktree.id}
           pendingDelete={pending() === worktree.id}
           busy={props.busy?.(worktree.id) ?? false}
-          working={runs()[worktree.id]?.state === "running"}
+          working={props.working?.(worktree.id) || runs()[worktree.id]?.state === "running"}
           stale={state()?.staleWorktreeIds?.includes(worktree.id) === true}
           stats={props.stats?.[worktree.id]}
+          shortcut={values().shortcut}
+          navHint={values().navHint}
           sessions={sessions(worktree.id).length}
           grouped={isGrouped(worktree)}
           groupStart={isGroupStart(worktree, idx(), list)}
@@ -229,8 +254,8 @@ export const ProjectSidebarBody: Component<Props> = (props) => {
           groupSize={worktree.groupId ? sorted().filter((item) => item.groupId === worktree.groupId).length : 0}
           renaming={renaming() === worktree.id}
           renameValue={name()}
-          closeKeybind=""
-          openKeybind=""
+          closeKeybind={values().closeKeybind}
+          openKeybind={values().openKeybind}
           pr={props.prs?.[worktree.id] ?? undefined}
           runStatus={runs()[worktree.id]}
           sections={sections()}
@@ -279,11 +304,21 @@ export const ProjectSidebarBody: Component<Props> = (props) => {
           data-sidebar-id={`${props.project.id}:local`}
           onClick={() => props.onSelectLocal(props.project.id)}
         >
-          <svg class="am-local-icon" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg">
-            <rect x="2.5" y="3.5" width="15" height="10" rx="1" stroke="currentColor" />
-            <path d="M6 16.5H14" stroke="currentColor" stroke-linecap="square" />
-            <path d="M10 13.5V16.5" stroke="currentColor" />
-          </svg>
+          <Show when={!props.localBusy?.()} fallback={<Spinner class="am-worktree-spinner" />}>
+            <svg class="am-local-icon" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg">
+              <rect x="2.5" y="3.5" width="15" height="10" rx="1" stroke="currentColor" />
+              <path d="M6 16.5H14" stroke="currentColor" stroke-linecap="square" />
+              <path d="M10 13.5V16.5" stroke="currentColor" />
+            </svg>
+          </Show>
+          <Show when={props.shortcutMap?.().get(`${props.project.id}:local`)}>
+            {(shortcut) => (
+              <span class="am-shortcut-badge">
+                {isMac ? "⌘" : "Ctrl+"}
+                {shortcut()}
+              </span>
+            )}
+          </Show>
           <div class="am-local-text">
             <span class="am-local-label">{props.t("agentManager.local")}</span>
             <Show when={props.local?.branch}>
@@ -313,20 +348,25 @@ export const ProjectSidebarBody: Component<Props> = (props) => {
         </button>
 
         <div class="am-section">
-          <div class="am-section-header">
-            <span class="am-section-label">{props.t("agentManager.section.worktrees")}</span>
-            <ProjectActions
-              branch={state()?.defaultBaseBranch ?? props.local?.branch ?? "main"}
-              bindings={props.bindings}
-              loaded={state() !== undefined}
-              t={props.t}
-              onCreate={() => post({ type: "agentManager.createWorktree" })}
-              onNew={() => props.onNewWorktree(props.project.id)}
-              onSection={() => createSection()}
-              onSetup={() => post({ type: "agentManager.configureSetupScript" })}
-              onBranch={() => props.onDefaultBranch(props.project.id, state()?.defaultBaseBranch, props.local?.branch)}
-            />
-          </div>
+          <SidebarSectionHeader
+            class="am-section-header"
+            label={<span class="am-section-label">{props.t("agentManager.section.worktrees")}</span>}
+            actions={
+              <ProjectActions
+                branch={state()?.defaultBaseBranch ?? props.local?.branch ?? "main"}
+                bindings={props.bindings}
+                loaded={state() !== undefined}
+                t={props.t}
+                onCreate={() => post({ type: "agentManager.createWorktree" })}
+                onNew={() => props.onNewWorktree(props.project.id)}
+                onSection={() => createSection()}
+                onSetup={() => post({ type: "agentManager.configureSetupScript" })}
+                onBranch={() =>
+                  props.onDefaultBranch(props.project.id, state()?.defaultBaseBranch, props.local?.branch)
+                }
+              />
+            }
+          />
           <div class="am-worktree-list">
             <DragDropProvider
               onDragStart={onDragStart}
diff --git a/packages/kilo-vscode/webview-ui/agent-manager/ProjectsSection.tsx b/packages/kilo-vscode/webview-ui/agent-manager/ProjectsSection.tsx
index c8b39b253d6..1e2dcb8fb8a 100644
--- a/packages/kilo-vscode/webview-ui/agent-manager/ProjectsSection.tsx
+++ b/packages/kilo-vscode/webview-ui/agent-manager/ProjectsSection.tsx
@@ -5,6 +5,7 @@ import { Icon } from "@kilocode/kilo-ui/icon"
 import { IconButton } from "@kilocode/kilo-ui/icon-button"
 import type { LanguageContextValue } from "../src/context/language"
 import type { AgentProjectSnapshot } from "../src/types/messages"
+import { SidebarSectionHeader } from "./SidebarSectionHeader"
 
 interface ProjectsSectionProps {
   projects: AgentProjectSnapshot[]
@@ -30,66 +31,75 @@ const ProjectBodySlot: Component<{
  */
 export const ProjectsSection: Component<ProjectsSectionProps> = (props) => (
   <div class="am-projects">
-    <div class="am-section-header">
-      <span class="am-section-label">{props.t("agentManager.projects")}</span>
-      <div class="am-projects-tools">
-        {props.tools}
-        <IconButton
-          icon="plus"
-          size="small"
-          variant="ghost"
-          label={props.t("agentManager.project.add")}
-          onClick={props.onAdd}
-        />
-      </div>
-    </div>
+    <SidebarSectionHeader
+      class="am-section-header"
+      label={<span class="am-section-label">{props.t("agentManager.projects")}</span>}
+      actions={
+        <div class="am-projects-tools">
+          {props.tools}
+          <IconButton
+            icon="plus"
+            size="small"
+            variant="ghost"
+            label={props.t("agentManager.project.add")}
+            onClick={props.onAdd}
+          />
+        </div>
+      }
+    />
     <div class="am-projects-list">
       <For each={props.projects.map((project) => project.id)}>
         {(id) => {
           const project = () => props.projects.find((item) => item.id === id)!
           return (
-            <div class="am-project" classList={{ "am-project-active": project().active }}>
-              <div class="am-project-item" data-project-id={project().id}>
-                <button
-                  class="am-project-main"
-                  title={project().missing ? props.t("agentManager.project.missing") : project().root}
-                  onClick={() => {
-                    if (project().active || project().missing) return
-                    if (project().trusted) props.onSelect(project().id)
-                    else props.onTrust(project().id)
-                  }}
-                >
-                  <span class="am-project-label">{project().label}</span>
-                  <Show when={props.count(project().id) !== undefined}>
-                    <span class="am-project-count">({props.count(project().id)})</span>
+            <div class="am-project">
+              <SidebarSectionHeader
+                class="am-project-item"
+                expanded={project().expanded}
+                ariaLabel={project().label}
+                title={project().missing ? props.t("agentManager.project.missing") : project().root}
+                label={
+                  <>
+                    <span class="am-project-label">{project().label}</span>
+                    <Show when={props.count(project().id) !== undefined}>
+                      <span class="am-project-count">({props.count(project().id)})</span>
+                    </Show>
+                    <Show when={project().missing}>
+                      <Icon name="warning" size="small" />
+                    </Show>
+                    <Show when={!project().trusted && !project().missing}>
+                      <span class="am-project-trust">
+                        <Icon name="lock" size="small" />
+                        {props.t("agentManager.project.trust")}
+                      </span>
+                    </Show>
+                  </>
+                }
+                actions={
+                  <Show when={!project().pinned}>
+                    <IconButton
+                      icon="close-small"
+                      size="small"
+                      variant="ghost"
+                      label={props.t("agentManager.project.remove")}
+                      onClick={(event) => {
+                        event.stopPropagation()
+                        props.onRemove(project().id)
+                      }}
+                    />
                   </Show>
-                  <Show when={project().missing}>
-                    <Icon name="warning" size="small" />
-                  </Show>
-                  <Show when={!project().trusted && !project().missing}>
-                    <span class="am-project-trust">
-                      <Icon name="lock" size="small" />
-                      {props.t("agentManager.project.trust")}
-                    </span>
-                  </Show>
-                </button>
-                <Show when={!project().pinned}>
-                  <IconButton
-                    icon="close-small"
-                    size="small"
-                    variant="ghost"
-                    label={props.t("agentManager.project.remove")}
-                    onClick={() => props.onRemove(project().id)}
-                  />
-                </Show>
-                <button
-                  class="am-project-chevron"
-                  aria-label={project().label}
-                  onClick={() => props.onExpand(project().id, !project().expanded)}
-                >
-                  <Icon name={project().expanded ? "chevron-down" : "chevron-right"} size="small" />
-                </button>
-              </div>
+                }
+                onToggle={() => {
+                  if (project().missing) return
+                  if (!project().trusted) {
+                    props.onTrust(project().id)
+                    return
+                  }
+                  const expanded = !project().expanded
+                  props.onExpand(project().id, expanded)
+                  if (!project().active && project().trusted) props.onSelect(project().id)
+                }}
+              />
               <Show when={project().expanded}>
                 <ProjectBodySlot project={project} body={props.body} />
               </Show>
diff --git a/packages/kilo-vscode/webview-ui/agent-manager/SectionHeader.tsx b/packages/kilo-vscode/webview-ui/agent-manager/SectionHeader.tsx
index 823b3c4800a..3bcd0ecbcec 100644
--- a/packages/kilo-vscode/webview-ui/agent-manager/SectionHeader.tsx
+++ b/packages/kilo-vscode/webview-ui/agent-manager/SectionHeader.tsx
@@ -5,6 +5,7 @@ import { Icon } from "@kilocode/kilo-ui/icon"
 import type { SectionState } from "../src/types/messages"
 import { SECTION_COLORS, colorCss } from "./section-colors"
 import { useLanguage } from "../src/context/language"
+import { SidebarSectionHeader } from "./SidebarSectionHeader"
 
 interface Props {
   section: SectionState
@@ -30,16 +31,23 @@ const SectionHeader: Component<Props> = (props) => {
   const { t } = useLanguage()
   const [renaming, setRenaming] = createSignal(false)
   const [value, setValue] = createSignal("")
+  let cancelled = false
 
   const border = () => colorCss(props.section.color) ?? "var(--vscode-panel-border)"
 
   const startRename = () => {
+    cancelled = false
     setValue(props.section.name)
     setRenaming(true)
   }
 
   const commit = () => {
+    if (cancelled) {
+      cancelled = false
+      return
+    }
     const trimmed = value().trim()
+    cancelled = true
     setRenaming(false)
     props.onRenameEnd?.()
     if (trimmed && trimmed !== props.section.name) {
@@ -48,6 +56,7 @@ const SectionHeader: Component<Props> = (props) => {
   }
 
   const cancel = () => {
+    cancelled = true
     setRenaming(false)
     props.onRenameEnd?.()
   }
@@ -56,11 +65,6 @@ const SectionHeader: Component<Props> = (props) => {
     if (props.autoRename && !renaming()) startRename()
   })
 
-  const handleClick = (e: MouseEvent) => {
-    if (e.button !== 0 || renaming()) return
-    props.onToggle()
-  }
-
   const droppable = createDroppable(props.dropId ?? props.section.id)
 
   return (
@@ -70,41 +74,44 @@ const SectionHeader: Component<Props> = (props) => {
       style={{ "--section-color": border() }}
     >
       <ContextMenu>
-        <ContextMenu.Trigger class="am-section-group-header" onClick={handleClick}>
-          <div class="am-section-group-left">
-            <Icon
-              name="chevron-down"
-              size="small"
-              class={`am-section-group-chevron ${props.section.collapsed ? "am-section-group-chevron-collapsed" : ""}`}
-            />
-            <Show
-              when={!renaming()}
-              fallback={
-                <input
-                  class="am-section-group-rename"
-                  value={value()}
-                  onInput={(e) => setValue(e.currentTarget.value)}
-                  onKeyDown={(e) => {
-                    if (e.key === "Enter") commit()
-                    if (e.key === "Escape") cancel()
-                  }}
-                  onBlur={commit}
-                  onClick={(e) => e.stopPropagation()}
-                  ref={(el) =>
-                    requestAnimationFrame(() =>
-                      requestAnimationFrame(() => {
-                        el.focus()
-                        el.select()
-                      }),
-                    )
-                  }
-                />
-              }
-            >
-              <span class="am-section-group-name">{props.section.name}</span>
-            </Show>
-          </div>
-          <span class="am-section-group-count">{props.count}</span>
+        <ContextMenu.Trigger as="div" style={{ display: "contents" }}>
+          <SidebarSectionHeader
+            class="am-section-group-header"
+            expanded={!props.section.collapsed}
+            ariaLabel={props.section.name}
+            label={
+              <Show
+                when={!renaming()}
+                fallback={
+                  <input
+                    class="am-section-group-rename"
+                    value={value()}
+                    onInput={(e) => setValue(e.currentTarget.value)}
+                    onKeyDown={(e) => {
+                      if (e.key === "Enter") commit()
+                      if (e.key === "Escape") cancel()
+                    }}
+                    onBlur={commit}
+                    onClick={(e) => e.stopPropagation()}
+                    ref={(el) =>
+                      requestAnimationFrame(() =>
+                        requestAnimationFrame(() => {
+                          el.focus()
+                          el.select()
+                        }),
+                      )
+                    }
+                  />
+                }
+              >
+                <span class="am-section-group-name">{props.section.name}</span>
+              </Show>
+            }
+            count={props.count}
+            onToggle={() => {
+              if (!renaming()) props.onToggle()
+            }}
+          />
         </ContextMenu.Trigger>
         <ContextMenu.Portal>
           <ContextMenu.Content class="am-ctx-menu">
diff --git a/packages/kilo-vscode/webview-ui/agent-manager/SidebarBody.tsx b/packages/kilo-vscode/webview-ui/agent-manager/SidebarBody.tsx
index a48c5c643c2..840ec8cfba6 100644
--- a/packages/kilo-vscode/webview-ui/agent-manager/SidebarBody.tsx
+++ b/packages/kilo-vscode/webview-ui/agent-manager/SidebarBody.tsx
@@ -28,6 +28,7 @@ import { sectionAwareDetector } from "./section-dnd"
 import { ConstrainDragXAxis } from "./constrain-drag-x"
 import { useVSCode } from "../src/context/vscode"
 import SectionHeader from "./SectionHeader"
+import { SidebarSectionHeader } from "./SidebarSectionHeader"
 import { WorktreeItem } from "./WorktreeItem"
 import { WorktreeSectionActions } from "./WorktreeSectionActions"
 import { UnassignedSessionsSection } from "./UnassignedSessionsSection"
@@ -183,26 +184,29 @@ export const SidebarBody: Component<SidebarBodyProps> = (props) => {
 
       {/* WORKTREES section */}
       <div class={`am-section ${props.sessionsCollapsed() ? "am-section-grow" : ""}`}>
-        <div class="am-section-header">
-          <span class="am-section-label">{props.t("agentManager.section.worktrees")}</span>
-          <WorktreeSectionActions
-            items={props.search.items}
-            current={props.search.current}
-            bindings={props.bindings()}
-            branch={props.defaultBranch()}
-            git={props.isGitRepo()}
-            loaded={props.loaded()}
-            t={props.t}
-            onRef={(value) => props.onSearchRef(value)}
-            onSelect={props.onSearchSelect}
-            onCreate={props.onCreateWorktree}
-            onNew={props.onNewWorktree}
-            onSection={props.onNewSection}
-            onShortcuts={props.onShortcuts}
-            onSetup={props.onSetup}
-            onBranch={props.onBranch}
-          />
-        </div>
+        <SidebarSectionHeader
+          class="am-section-header"
+          label={<span class="am-section-label">{props.t("agentManager.section.worktrees")}</span>}
+          actions={
+            <WorktreeSectionActions
+              items={props.search.items}
+              current={props.search.current}
+              bindings={props.bindings()}
+              branch={props.defaultBranch()}
+              git={props.isGitRepo()}
+              loaded={props.loaded()}
+              t={props.t}
+              onRef={(value) => props.onSearchRef(value)}
+              onSelect={props.onSearchSelect}
+              onCreate={props.onCreateWorktree}
+              onNew={props.onNewWorktree}
+              onSection={props.onNewSection}
+              onShortcuts={props.onShortcuts}
+              onSetup={props.onSetup}
+              onBranch={props.onBranch}
+            />
+          }
+        />
         <div class="am-worktree-list">
           <Show
             when={props.worktreesLoaded() && props.sessionsLoaded()}
diff --git a/packages/kilo-vscode/webview-ui/agent-manager/SidebarSectionHeader.tsx b/packages/kilo-vscode/webview-ui/agent-manager/SidebarSectionHeader.tsx
new file mode 100644
index 00000000000..ebbc69446c9
--- /dev/null
+++ b/packages/kilo-vscode/webview-ui/agent-manager/SidebarSectionHeader.tsx
@@ -0,0 +1,52 @@
+import { Show, type Component, type JSX } from "solid-js"
+import { Icon } from "@kilocode/kilo-ui/icon"
+
+interface Props {
+  label: JSX.Element
+  expanded?: boolean
+  onToggle?: () => void
+  count?: JSX.Element
+  actions?: JSX.Element
+  class?: string
+  title?: string
+  ariaLabel?: string
+}
+
+/** Shared layout for sidebar headings with a fixed leading control column. */
+export const SidebarSectionHeader: Component<Props> = (props) => {
+  return (
+    <div
+      class={`am-sidebar-header${props.onToggle ? " am-sidebar-header-toggleable" : ""}${props.class ? ` ${props.class}` : ""}`}
+      title={props.title}
+      onClick={(event) => {
+        if (event.button === 0) props.onToggle?.()
+      }}
+    >
+      <div class="am-sidebar-header-main">
+        <Show when={props.onToggle}>
+          <button
+            class="am-sidebar-header-toggle"
+            type="button"
+            aria-expanded={props.expanded}
+            aria-label={props.ariaLabel}
+            onClick={(event) => {
+              event.stopPropagation()
+              props.onToggle?.()
+            }}
+          >
+            <span class="am-sidebar-header-chevron" aria-hidden="true">
+              <Icon name={props.expanded ? "chevron-down" : "chevron-right"} size="small" />
+            </span>
+          </button>
+        </Show>
+        <div class="am-sidebar-header-label">{props.label}</div>
+      </div>
+      <Show when={props.count !== undefined}>
+        <span class="am-sidebar-header-count">{props.count}</span>
+      </Show>
+      <Show when={props.actions !== undefined}>
+        <div class="am-sidebar-header-actions">{props.actions}</div>
+      </Show>
+    </div>
+  )
+}
diff --git a/packages/kilo-vscode/webview-ui/agent-manager/UnassignedSessionsSection.tsx b/packages/kilo-vscode/webview-ui/agent-manager/UnassignedSessionsSection.tsx
index 966fee8234e..625780bc1cc 100644
--- a/packages/kilo-vscode/webview-ui/agent-manager/UnassignedSessionsSection.tsx
+++ b/packages/kilo-vscode/webview-ui/agent-manager/UnassignedSessionsSection.tsx
@@ -6,6 +6,7 @@ import { Tooltip } from "@kilocode/kilo-ui/tooltip"
 import type { SessionInfo } from "../src/types/messages"
 import { useLanguage } from "../src/context/language"
 import { formatRelativeDate } from "../src/utils/date"
+import { SidebarSectionHeader } from "./SidebarSectionHeader"
 
 interface Props {
   sessions: Accessor<SessionInfo[]>
@@ -29,12 +30,13 @@ export const UnassignedSessionsSection: Component<Props> = (props) => {
 
   return (
     <div class={`am-section ${props.collapsed() ? "" : "am-section-grow"}`}>
-      <button class="am-section-header am-section-toggle" onClick={props.onToggle}>
-        <span class="am-section-label">
-          <Icon name={props.collapsed() ? "chevron-right" : "chevron-down"} size="small" class="am-section-chevron" />
-          {t("agentManager.section.sessions")}
-        </span>
-      </button>
+      <SidebarSectionHeader
+        class="am-section-header am-section-toggle"
+        expanded={!props.collapsed()}
+        ariaLabel={t("agentManager.section.sessions")}
+        label={<span class="am-section-label">{t("agentManager.section.sessions")}</span>}
+        onToggle={props.onToggle}
+      />
       <Show when={!props.collapsed()}>
         <div class="am-list">
           <Show
diff --git a/packages/kilo-vscode/webview-ui/agent-manager/agent-manager.css b/packages/kilo-vscode/webview-ui/agent-manager/agent-manager.css
index 3e782baa2ac..76c7c6e3b74 100644
--- a/packages/kilo-vscode/webview-ui/agent-manager/agent-manager.css
+++ b/packages/kilo-vscode/webview-ui/agent-manager/agent-manager.css
@@ -181,6 +181,83 @@ html[data-theme="kilo-vscode"]
   min-height: 0;
 }
 
+.am-sidebar-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  min-width: 0;
+  box-sizing: border-box;
+}
+
+.am-sidebar-header-toggleable {
+  cursor: pointer;
+  user-select: none;
+}
+
+.am-sidebar-header-main {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  flex: 1;
+  min-width: 0;
+}
+
+.am-sidebar-header-chevron {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 16px;
+  height: 16px;
+  flex-shrink: 0;
+  color: var(--text-weak);
+}
+
+.am-sidebar-header-toggle {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 16px;
+  height: 16px;
+  flex-shrink: 0;
+  padding: 0;
+  color: inherit;
+  background: none;
+  border: 0;
+  border-radius: var(--radius-sm);
+  cursor: pointer;
+}
+
+.am-sidebar-header-toggle:hover {
+  color: var(--text-base);
+  background: var(--surface-inset-base-hover);
+}
+
+.am-sidebar-header-label {
+  display: flex;
+  align-items: center;
+  min-width: 0;
+  flex: 1;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.am-sidebar-header-actions {
+  display: flex;
+  align-items: center;
+  gap: 2px;
+  flex-shrink: 0;
+}
+
+.am-sidebar-header-count {
+  flex-shrink: 0;
+  min-width: 14px;
+  color: var(--text-weaker);
+  font-size: var(--kilo-font-size-10);
+  text-align: center;
+}
+
 .am-section-grow {
   flex: 1;
   min-height: 0;
@@ -193,6 +270,10 @@ html[data-theme="kilo-vscode"]
   padding: 4px 8px 2px;
 }
 
+.am-project-body .am-section-header {
+  padding-left: 6px;
+}
+
 .am-section-label {
   font-size: var(--font-size-small);
   font-weight: 600;
@@ -241,23 +322,7 @@ html[data-theme="kilo-vscode"]
   border-bottom: 0;
 }
 
-.am-project::before {
-  content: "";
-  position: absolute;
-  inset: 6px auto 6px 0;
-  width: 2px;
-  border-radius: 0 2px 2px 0;
-  background: transparent;
-}
-
-.am-project-active::before {
-  background: var(--border-interactive-base);
-}
-
 .am-project-item {
-  display: flex;
-  align-items: center;
-  gap: 2px;
   min-height: 34px;
   padding: 6px 8px 6px 12px;
   box-sizing: border-box;
@@ -267,21 +332,11 @@ html[data-theme="kilo-vscode"]
   background: var(--surface-inset-base-hover);
 }
 
-.am-project-main {
-  display: flex;
-  align-items: center;
+.am-project-item .am-sidebar-header-label {
   gap: 6px;
-  flex: 1;
-  min-width: 0;
-  padding: 0;
-  background: none;
-  border: none;
   color: inherit;
-  font-family: inherit;
   font-size: var(--font-size-base);
   font-weight: 500;
-  text-align: left;
-  cursor: pointer;
 }
 
 .am-project-label {
@@ -307,30 +362,6 @@ html[data-theme="kilo-vscode"]
   color: var(--text-weak);
 }
 
-.am-project-chevron {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  width: 22px;
-  height: 22px;
-  flex-shrink: 0;
-  background: none;
-  border: none;
-  border-radius: var(--radius-sm);
-  color: var(--text-weak);
-  cursor: pointer;
-  padding: 0;
-}
-
-.am-project-chevron:hover {
-  background: var(--surface-inset-base-hover);
-  color: var(--text-base);
-}
-
-.am-project-chevron:disabled {
-  cursor: default;
-}
-
 .am-project-body {
   display: flex;
   flex-direction: column;
@@ -355,25 +386,10 @@ html[data-theme="kilo-vscode"]
 
 /* Collapsible section toggle */
 
-button.am-section-toggle {
-  all: unset;
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  padding: 4px 8px 2px;
-  cursor: pointer;
-  width: 100%;
-  box-sizing: border-box;
-}
-
-button.am-section-toggle:hover .am-section-label {
+.am-section-toggle:hover .am-section-label {
   color: var(--text-base);
 }
 
-.am-section-chevron {
-  flex-shrink: 0;
-}
-
 .am-section-actions {
   display: flex;
   align-items: center;
@@ -988,12 +1004,7 @@ button.am-section-toggle:hover .am-section-label {
 }
 
 .am-section-group-header {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  padding: 5px 10px 5px 6px;
-  cursor: pointer;
-  user-select: none;
+  padding: 5px 10px 5px 4px;
   border-radius: var(--radius-sm);
   font-size: var(--kilo-font-size-11);
   font-weight: 500;
@@ -1006,38 +1017,12 @@ button.am-section-toggle:hover .am-section-label {
   background: var(--surface-interactive-hover, var(--vscode-list-hoverBackground));
 }
 
-.am-section-group-left {
-  display: flex;
-  align-items: center;
-  gap: 4px;
-  min-width: 0;
-  overflow: hidden;
-}
-
-.am-section-group-chevron {
-  flex-shrink: 0;
-  opacity: 0.7;
-  transition: transform 120ms ease;
-}
-
-.am-section-group-chevron-collapsed {
-  transform: rotate(-90deg);
-}
-
 .am-section-group-name {
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
 }
 
-.am-section-group-count {
-  flex-shrink: 0;
-  font-size: var(--kilo-font-size-10);
-  color: var(--text-weaker);
-  min-width: 14px;
-  text-align: center;
-}
-
 .am-section-group-body {
   padding-left: 4px;
 }
diff --git a/packages/kilo-vscode/webview-ui/agent-manager/focus.ts b/packages/kilo-vscode/webview-ui/agent-manager/focus.ts
index e1acb284611..0553003b306 100644
--- a/packages/kilo-vscode/webview-ui/agent-manager/focus.ts
+++ b/packages/kilo-vscode/webview-ui/agent-manager/focus.ts
@@ -1,5 +1,11 @@
+import { isTextControl } from "../src/utils/focus"
+
 const OPTION = '[data-component="question-dock"] button[data-slot="question-option"]'
 
+/** Keep an active editor, such as the worktree rename input, in control. */
+export const preservesTextFocus = (active: Element | null): boolean =>
+  active !== null && isTextControl(active) && !active.classList.contains("prompt-input")
+
 export function createChatFocus(deps: {
   term: () => string | undefined
   history: () => boolean
@@ -7,6 +13,7 @@ export function createChatFocus(deps: {
 }) {
   const focus = (force: boolean) => {
     if ((!force && !document.hasFocus()) || deps.term() || deps.history() || deps.review()) return
+    if (preservesTextFocus(document.activeElement)) return
     if (!force && document.activeElement?.matches('[role="tab"]')) return
     if (!force && document.activeElement?.closest('[data-component="question-dock"]')) return
     if (focusQuestionOption()) return
diff --git a/packages/kilo-vscode/webview-ui/agent-manager/initial-message.ts b/packages/kilo-vscode/webview-ui/agent-manager/initial-message.ts
index 15049eec698..7f210d4a560 100644
--- a/packages/kilo-vscode/webview-ui/agent-manager/initial-message.ts
+++ b/packages/kilo-vscode/webview-ui/agent-manager/initial-message.ts
@@ -9,6 +9,7 @@ export function initialMessage(ev: AgentManagerSendInitialMessage): SendMessageR
   if (!ev.text) return undefined
   return {
     type: "sendMessage",
+    ...(ev.projectId ? { projectId: ev.projectId } : {}),
     text: ev.text,
     sessionID: ev.sessionId,
     providerID: ev.providerID,
diff --git a/packages/kilo-vscode/webview-ui/agent-manager/navigate.ts b/packages/kilo-vscode/webview-ui/agent-manager/navigate.ts
index 6fad2144f44..8596666cf91 100644
--- a/packages/kilo-vscode/webview-ui/agent-manager/navigate.ts
+++ b/packages/kilo-vscode/webview-ui/agent-manager/navigate.ts
@@ -7,6 +7,8 @@
  * Returns the action to take: select a session by ID, go to local, or do nothing.
  */
 
+import { sortWorktrees } from "./section-helpers"
+
 /** Sentinel value for the local repo selection. */
 export const LOCAL = "local" as const
 
@@ -137,8 +139,8 @@ export function focusChatSearch(reset: { history(v: boolean): void; review(v: bo
  * Multi-project navigation.
  *
  * In multi-project mode the sidebar shows an accordion of projects; each
- * expanded project renders its own Local item, worktrees (sections first,
- * then ungrouped), and an unassigned-sessions list. Keyboard previous/next
+ * expanded project renders its own Local item, ungrouped worktrees, section
+ * members, and an unassigned-sessions list. Keyboard previous/next
  * and numeric shortcuts must traverse every expanded project in visual
  * order, not just the active one.
  *
@@ -160,7 +162,9 @@ export interface NavEntry {
 export interface ProjectNavInput {
   id: string
   expanded: boolean
-  worktrees: { id: string; sectionId?: string }[]
+  worktrees: { id: string; sectionId?: string; groupId?: string }[]
+  /** Persisted top-level order containing worktree and section IDs. */
+  worktreeOrder?: string[]
   sections: { id: string; collapsed: boolean }[]
   sessionsCollapsed: boolean
   /** Visible unassigned (root, no worktree) sessions in render order. */
@@ -174,10 +178,10 @@ export const sessionNavId = (projectId: string, sessionId: string) => `${project
 /**
  * Build one global visual order across expanded projects.
  *
- * For each expanded project (in input order): Local, then worktrees in the
- * order the multi-project body renders them (each non-collapsed section's
- * members, then ungrouped), then visible unassigned sessions (when the
- * sessions section is not collapsed). Collapsed projects contribute nothing.
+ * For each expanded project (in input order): Local, then ungrouped worktrees,
+ * then members of each non-collapsed section in top-level order, then visible
+ * unassigned sessions. This matches `buildTopLevelItems` and the project body.
+ * Collapsed projects contribute nothing.
  */
 export function buildProjectNavOrder(projects: ProjectNavInput[]): NavEntry[] {
   const order: NavEntry[] = []
@@ -185,19 +189,28 @@ export function buildProjectNavOrder(projects: ProjectNavInput[]): NavEntry[] {
     if (!p.expanded) continue
     const pid = p.id
     order.push({ id: localNavId(pid), target: { projectId: pid, kind: "local" } })
-    for (const sec of p.sections) {
+    const worktrees = sortWorktrees(p.worktrees, p.worktreeOrder ?? [])
+    const rank = new Map((p.worktreeOrder ?? []).map((id, index) => [id, index] as const))
+    const ungrouped = worktrees.filter((w) => !w.sectionId)
+    if (p.sections.length > 0) {
+      ungrouped.sort(
+        (a, b) => (rank.get(a.id) ?? Number.MAX_SAFE_INTEGER) - (rank.get(b.id) ?? Number.MAX_SAFE_INTEGER),
+      )
+    }
+    const secs = [...p.sections].sort(
+      (a, b) => (rank.get(a.id) ?? Number.MAX_SAFE_INTEGER) - (rank.get(b.id) ?? Number.MAX_SAFE_INTEGER),
+    )
+    for (const w of ungrouped) {
+      order.push({ id: worktreeNavId(pid, w.id), target: { projectId: pid, kind: "worktree", worktreeId: w.id } })
+    }
+    for (const sec of secs) {
       if (sec.collapsed) continue
-      for (const w of p.worktrees) {
+      for (const w of worktrees) {
         if (w.sectionId === sec.id) {
           order.push({ id: worktreeNavId(pid, w.id), target: { projectId: pid, kind: "worktree", worktreeId: w.id } })
         }
       }
     }
-    for (const w of p.worktrees) {
-      if (!w.sectionId) {
-        order.push({ id: worktreeNavId(pid, w.id), target: { projectId: pid, kind: "worktree", worktreeId: w.id } })
-      }
-    }
     if (!p.sessionsCollapsed) {
       for (const s of p.unassigned) {
         order.push({ id: sessionNavId(pid, s.id), target: { projectId: pid, kind: "session", sessionId: s.id } })
diff --git a/packages/kilo-vscode/webview-ui/agent-manager/project-local-navigation.ts b/packages/kilo-vscode/webview-ui/agent-manager/project-local-navigation.ts
new file mode 100644
index 00000000000..8e963f62f81
--- /dev/null
+++ b/packages/kilo-vscode/webview-ui/agent-manager/project-local-navigation.ts
@@ -0,0 +1,47 @@
+import { adjacentHint, worktreeNavId } from "./navigate"
+import { buildSidebarOrder } from "./section-helpers"
+
+export function projectSidebarOrder(...args: Parameters<typeof buildSidebarOrder>): string[] {
+  return buildSidebarOrder(...args).map((item) => item.id)
+}
+
+export function projectAdjacentHint(
+  projectId: string,
+  activeProjectId: string | undefined,
+  itemId: string,
+  activeId: string | undefined,
+  flatIds: string[],
+  prev: string,
+  next: string,
+): string {
+  if (projectId !== activeProjectId) return ""
+  return adjacentHint(itemId, activeId, flatIds, prev, next)
+}
+
+interface Input {
+  projectId: string
+  activeProjectId?: string
+  worktreeId: string
+  activeId?: string
+  flatIds: string[]
+  bindings: Record<string, string>
+  shortcuts?: Map<string, number>
+}
+
+/** Resolve the project-scoped values rendered by one worktree row. */
+export function projectWorktreeRow(input: Input) {
+  return {
+    shortcut: input.shortcuts?.get(worktreeNavId(input.projectId, input.worktreeId)),
+    navHint: projectAdjacentHint(
+      input.projectId,
+      input.activeProjectId,
+      input.worktreeId,
+      input.activeId,
+      input.flatIds,
+      input.bindings.previousSession ?? "",
+      input.bindings.nextSession ?? "",
+    ),
+    closeKeybind: input.bindings.closeWorktree ?? "",
+    openKeybind: input.bindings.openWorktree ?? "",
+  }
+}
diff --git a/packages/kilo-vscode/webview-ui/agent-manager/project-nav.ts b/packages/kilo-vscode/webview-ui/agent-manager/project-nav.ts
index beae37660cc..2ff2fdbe84f 100644
--- a/packages/kilo-vscode/webview-ui/agent-manager/project-nav.ts
+++ b/packages/kilo-vscode/webview-ui/agent-manager/project-nav.ts
@@ -19,7 +19,7 @@ import type { AgentManagerStateMessage, AgentProjectSnapshot, ProjectSessionInfo
  *
  * Handles previous/next (⌘⌥↑/↓) and numeric-shortcut (⌘1-9) navigation across
  * the sidebar. In multi-project mode it builds one global visual order across
- * every expanded project — Local, worktrees (sections first, then ungrouped),
+ * every expanded project — Local, ungrouped worktrees, then section members,
  * and visible unassigned sessions — using stable project-qualified composite
  * ids, and activates each target with a single atomic
  * `agentManager.activateSelection` dispatch. In single-project mode it keeps
@@ -48,6 +48,31 @@ export interface ProjectNav {
   jump: (index: number) => void
 }
 
+/** Build the same global order used by keyboard navigation and shortcut badges. */
+export function buildProjectNavEntries(
+  projects: AgentProjectSnapshot[],
+  states: Record<string, AgentManagerStateMessage>,
+  sessions: Record<string, ProjectSessionInfo[]>,
+): NavEntry[] {
+  return buildProjectNavOrder(
+    projects.map((p) => {
+      const st = states[p.id]
+      if (!st) {
+        return { id: p.id, expanded: false, worktrees: [], sections: [], sessionsCollapsed: false, unassigned: [] }
+      }
+      return {
+        id: p.id,
+        expanded: p.expanded,
+        worktrees: (st.worktrees ?? []).map((w) => ({ id: w.id, sectionId: w.sectionId, groupId: w.groupId })),
+        worktreeOrder: st.worktreeOrder,
+        sections: (st.sections ?? []).map((s) => ({ id: s.id, collapsed: s.collapsed })),
+        sessionsCollapsed: st.sessionsCollapsed === true,
+        unassigned: (sessions[p.id] ?? []).filter((s) => s.worktreeId === null).map((s) => ({ id: s.id })),
+      }
+    }),
+  )
+}
+
 /** DOM selector for the sidebar element backing a nav target. */
 export const navSelector = (target: NavTarget): string => {
   if (target.kind === "local") return `[data-sidebar-id="${target.projectId}:local"]`
@@ -74,24 +99,7 @@ export function createProjectNav(
     if (!deps.multiProject()) return []
     const states = deps.states()
     const live = deps.sessions()
-    return buildProjectNavOrder(
-      deps.projects().map((p) => {
-        const st = states[p.id]
-        // Until a project's state payload arrives its body shows a spinner
-        // (no Local/worktrees/sessions) — exclude it from the nav order.
-        if (!st) {
-          return { id: p.id, expanded: false, worktrees: [], sections: [], sessionsCollapsed: false, unassigned: [] }
-        }
-        return {
-          id: p.id,
-          expanded: p.expanded,
-          worktrees: (st.worktrees ?? []).map((w) => ({ id: w.id, sectionId: w.sectionId })),
-          sections: (st.sections ?? []).map((s) => ({ id: s.id, collapsed: s.collapsed })),
-          sessionsCollapsed: st.sessionsCollapsed === true,
-          unassigned: (live[p.id] ?? []).filter((s) => s.worktreeId === null).map((s) => ({ id: s.id })),
-        }
-      }),
-    )
+    return buildProjectNavEntries(deps.projects(), states, live)
   })
 
   const currentId = createMemo((): string | undefined => {
diff --git a/packages/kilo-vscode/webview-ui/agent-manager/project/local-tabs.ts b/packages/kilo-vscode/webview-ui/agent-manager/project/local-tabs.ts
index ea57612e34e..9bcf91a378b 100644
--- a/packages/kilo-vscode/webview-ui/agent-manager/project/local-tabs.ts
+++ b/packages/kilo-vscode/webview-ui/agent-manager/project/local-tabs.ts
@@ -2,13 +2,14 @@ import { createEffect, createMemo, onCleanup } from "solid-js"
 import type { SessionInfo } from "../../src/types/messages/sessions"
 
 /**
- * Persist open tabs and the sidebar width to webview state for recovery.
+ * Persist open tabs and panel widths to webview state for recovery.
  * Debounced so a resize drag does not serialize state on every pixel.
  */
 export function persistLocalTabs(opts: {
   tabs: () => Record<string, string[]>
   key: () => string
   width: () => number
+  panelWidth?: () => number
   get: () => Record<string, unknown> | undefined
   set: (value: Record<string, unknown>) => void
 }): void {
@@ -18,9 +19,16 @@ export function persistLocalTabs(opts: {
     const tabs = opts.tabs()
     const key = opts.key()
     const width = opts.width()
+    const panel = opts.panelWidth?.()
     clearTimeout(timer)
     timer = setTimeout(() => {
-      opts.set({ ...(opts.get() ?? {}), localTabs: tabs, localSessionIDs: tabs[key] ?? [], sidebarWidth: width })
+      opts.set({
+        ...(opts.get() ?? {}),
+        localTabs: tabs,
+        localSessionIDs: tabs[key] ?? [],
+        sidebarWidth: width,
+        ...(panel === undefined ? {} : { sidePanelWidth: panel }),
+      })
     }, 300)
   })
   onCleanup(() => clearTimeout(timer))
diff --git a/packages/kilo-vscode/webview-ui/agent-manager/project/progress.ts b/packages/kilo-vscode/webview-ui/agent-manager/project/progress.ts
new file mode 100644
index 00000000000..0a626885c7b
--- /dev/null
+++ b/packages/kilo-vscode/webview-ui/agent-manager/project/progress.ts
@@ -0,0 +1,26 @@
+import type { ProjectStore } from "./store"
+
+/** Clear setup indicators for every worktree in one multi-version group. */
+export function clearMultiVersionBusy(store: ProjectStore, groupId: string): void {
+  const ids = new Set(
+    store
+      .worktrees()
+      .filter((wt) => wt.groupId === groupId)
+      .map((wt) => wt.id),
+  )
+  if (ids.size === 0) return
+  store.setBusy((prev) => new Map([...prev].filter(([id, busy]) => !ids.has(id) || busy.reason === "deleting")))
+}
+
+/** Keep a newly created grouped worktree showing progress until its prompt starts. */
+export function markMultiVersionBusy(store: ProjectStore, sessionId: string): void {
+  const session = store.managedSessions().find((item) => item.id === sessionId)
+  const id = session?.worktreeId
+  if (!id) return
+  const worktree = store.worktrees().find((item) => item.id === id)
+  if (!worktree?.groupId) return
+  store.setBusy((prev) => {
+    if (prev.get(id)?.reason === "deleting") return prev
+    return new Map([...prev, [id, { reason: "setting-up" as const }]])
+  })
+}
diff --git a/packages/kilo-vscode/webview-ui/agent-manager/section-helpers.ts b/packages/kilo-vscode/webview-ui/agent-manager/section-helpers.ts
index c79eb3c5378..fba922c053d 100644
--- a/packages/kilo-vscode/webview-ui/agent-manager/section-helpers.ts
+++ b/packages/kilo-vscode/webview-ui/agent-manager/section-helpers.ts
@@ -10,11 +10,11 @@ export type TopLevelItem = { kind: "section"; section: SectionState } | { kind:
 export type SidebarItem = { type: "local" | "wt" | "session"; id: string }
 
 /** Apply persisted order while keeping multi-version worktrees adjacent. */
-export function sortWorktrees(all: WorktreeState[], order: string[]): WorktreeState[] {
+export function sortWorktrees<T extends { id: string; groupId?: string }>(all: T[], order: string[]): T[] {
   const ordered = applyTabOrder(all, order)
   if (ordered.length === 0) return []
 
-  const groups = new Map<string, WorktreeState[]>()
+  const groups = new Map<string, T[]>()
   for (const wt of ordered) {
     if (!wt.groupId) continue
     const group = groups.get(wt.groupId) ?? []
@@ -22,7 +22,7 @@ export function sortWorktrees(all: WorktreeState[], order: string[]): WorktreeSt
     groups.set(wt.groupId, group)
   }
 
-  const result: WorktreeState[] = []
+  const result: T[] = []
   const placed = new Set<string>()
   for (const wt of ordered) {
     if (placed.has(wt.id)) continue
@@ -145,7 +145,7 @@ export function buildSidebarOrder(
 }
 
 /** Build a map from sidebar item id → 1-based shortcut number (1 for LOCAL, 2+ for worktrees). */
-export function buildShortcutMap(order: SidebarItem[]): Map<string, number> {
+export function buildShortcutMap(order: { id: string }[]): Map<string, number> {
   const map = new Map<string, number>()
   for (let i = 0; i < order.length && i < 9; i++) {
     map.set(order[i]!.id, i + 1)
diff --git a/packages/kilo-vscode/webview-ui/agent-manager/side-panel-layout.ts b/packages/kilo-vscode/webview-ui/agent-manager/side-panel-layout.ts
new file mode 100644
index 00000000000..8cfaafe4f9e
--- /dev/null
+++ b/packages/kilo-vscode/webview-ui/agent-manager/side-panel-layout.ts
@@ -0,0 +1,25 @@
+export const MIN_PANEL_WIDTH = 360
+const DEFAULT_PANEL_WIDTH_RATIO = 0.5
+const MAX_PANEL_WIDTH_RATIO = 0.8
+
+function viewportWidth(viewport: number): number {
+  return Number.isFinite(viewport) && viewport > 0 ? viewport : MIN_PANEL_WIDTH
+}
+
+export function minPanelWidth(viewport: number): number {
+  const width = viewportWidth(viewport)
+  return Math.min(MIN_PANEL_WIDTH, Math.round(width * DEFAULT_PANEL_WIDTH_RATIO))
+}
+
+export function maxPanelWidth(viewport: number): number {
+  const width = viewportWidth(viewport)
+  return Math.max(minPanelWidth(width), Math.round(width * MAX_PANEL_WIDTH_RATIO))
+}
+
+/** Restore or constrain the shared inspector width without trusting saved state. */
+export function clampPanelWidth(value: unknown, viewport: number): number {
+  const width = viewportWidth(viewport)
+  const fallback = Math.round(width * DEFAULT_PANEL_WIDTH_RATIO)
+  const candidate = typeof value === "number" && Number.isFinite(value) ? value : fallback
+  return Math.round(Math.max(minPanelWidth(width), Math.min(candidate, maxPanelWidth(width))))
+}
diff --git a/packages/kilo-vscode/webview-ui/agent-manager/terminal/TerminalTab.tsx b/packages/kilo-vscode/webview-ui/agent-manager/terminal/TerminalTab.tsx
index 8ae231cacb4..606c8fa47ec 100644
--- a/packages/kilo-vscode/webview-ui/agent-manager/terminal/TerminalTab.tsx
+++ b/packages/kilo-vscode/webview-ui/agent-manager/terminal/TerminalTab.tsx
@@ -158,39 +158,6 @@ export const TerminalTab: Component<Props> = (props) => {
     })
     const fit = new FitAddon()
     term.loadAddon(fit)
-    // Clickable URLs in terminal output (Cmd/Ctrl+click to open).
-    // WebLinksAddon's default handler calls `window.open`, which VS Code
-    // webviews intercept and silently drop — so we pass an explicit
-    // handler that posts an `openExternal` message. The message falls
-    // through `AgentManagerProvider.onMessage` to the underlying
-    // `KiloProvider.handleWebviewMessage` path which already calls
-    // `vscode.env.openExternal` for sidebar + settings links.
-    term.loadAddon(
-      new WebLinksAddon((_event, url) => {
-        vscode.postMessage({ type: "openExternal", url })
-      }),
-    )
-    // OSC 52 clipboard support — lets shell programs (tmux, neovim, etc.)
-    // copy to the system clipboard via escape sequences. Writes always
-    // work in the webview; reads require the clipboard-read permission,
-    // which VS Code does not grant by default, so paste-from-escape
-    // silently falls back to no-op. Acceptable trade-off.
-    term.loadAddon(new ClipboardAddon())
-    // Unicode 15 grapheme-aware width tables. Fixes cell width for
-    // emoji introduced in Unicode 12-15 (🫠 melting face, 🫡 salute,
-    // 🧌 troll, and ~400 others) plus ZWJ grapheme sequences like
-    // 👨‍👩‍👧‍👦 and 🏳️‍🌈. The older `@xterm/addon-unicode11` (which VS
-    // Code's integrated terminal still uses) stops at Unicode 11
-    // (2018), leaving all post-2020 emoji rendered with wrong width —
-    // the canvas cuts them off in the DOM renderer and cursor math
-    // drifts by one cell per emoji. VS Code hides this visually with
-    // WebGL; in a webview we don't have that fallback, so we fix it
-    // at the buffer-width layer instead. Addon is marked
-    // "experimental" in its README but has been stable on npm since
-    // 2023, is shipped by the same maintainer as the core xterm.js
-    // package, and has no open bugs as of v0.4.0.
-    term.loadAddon(new UnicodeGraphemesAddon())
-    term.unicode.activeVersion = "15-graphemes"
     term.open(host)
     // Fit on the next frame — `host` might still have 0px dimensions
     // during the initial layout pass otherwise.
@@ -232,6 +199,8 @@ export const TerminalTab: Component<Props> = (props) => {
     let fallbackTimer: ReturnType<typeof setTimeout> | undefined
     let streamed = false
     let socketEnded = false
+    let frame: number | undefined
+    let deferred: number | undefined
     // The failure line must not depend on event ordering: the stream can
     // close before the exited snapshot lands (fast failures), or stay open
     // when a background child outlives the script. Write it exactly once,
@@ -358,6 +327,34 @@ export const TerminalTab: Component<Props> = (props) => {
     }
     const disposeData = term.onData(send)
     open(props.wsUrl)
+
+    // These addons are not needed to paint the initial prompt. Defer them
+    // until after the first frame so their startup work, especially the
+    // Unicode 15 width tables, does not delay the shell connection.
+    const loadAddons = () => {
+      deferred = undefined
+      if (closed) return
+
+      // Clickable URLs in terminal output (Cmd/Ctrl+click to open).
+      // WebLinksAddon's default handler calls `window.open`, which VS Code
+      // webviews intercept and silently drop, so post an explicit message.
+      term.loadAddon(
+        new WebLinksAddon((_event, url) => {
+          vscode.postMessage({ type: "openExternal", url })
+        }),
+      )
+      // OSC 52 clipboard support for shell programs such as tmux and neovim.
+      term.loadAddon(new ClipboardAddon())
+      // Use grapheme-aware width tables for newer emoji and ZWJ sequences.
+      term.loadAddon(new UnicodeGraphemesAddon())
+      term.unicode.activeVersion = "15-graphemes"
+      term.refresh(0, Math.max(0, term.rows - 1))
+    }
+    frame = requestAnimationFrame(() => {
+      frame = undefined
+      deferred = requestAnimationFrame(loadAddons)
+    })
+
     const restarted = (url: string) => {
       open(url)
     }
@@ -525,6 +522,8 @@ export const TerminalTab: Component<Props> = (props) => {
     onCleanup(() => {
       closed = true
       if (pendingFrame !== null) cancelAnimationFrame(pendingFrame)
+      if (frame !== undefined) cancelAnimationFrame(frame)
+      if (deferred !== undefined) cancelAnimationFrame(deferred)
       document.removeEventListener("visibilitychange", onVisibilityChange)
       window.removeEventListener("focus", onWindowFocus)
       host.removeEventListener("focusin", onFocusIn)
diff --git a/packages/kilo-vscode/webview-ui/diff-viewer/DiffViewerApp.tsx b/packages/kilo-vscode/webview-ui/diff-viewer/DiffViewerApp.tsx
index 5ab642292e1..08115371429 100644
--- a/packages/kilo-vscode/webview-ui/diff-viewer/DiffViewerApp.tsx
+++ b/packages/kilo-vscode/webview-ui/diff-viewer/DiffViewerApp.tsx
@@ -24,6 +24,7 @@ import type { DiffViewerNotice } from "../src/types/messages/extension-messages"
 import { DiffPickerHeader } from "./DiffPickerHeader"
 import { BaseBranchPicker } from "./BaseBranchPicker"
 import { SpeechToTextPrewarm } from "../src/components/speech-to-text/SpeechToTextPrewarm"
+import { SpeechToTextModelsProvider } from "../src/context/speech-to-text-models"
 
 const NOTICE_KEYS: Record<DiffViewerNotice, string> = {
   "snapshots-disabled": "diffViewer.notice.snapshotsDisabled",
@@ -306,8 +307,10 @@ export const DiffViewerApp: Component = () => {
           <ServerProvider>
             <ProviderProvider>
               <ConfigProvider>
-                <SpeechToTextPrewarm />
-                <DiffViewerShell />
+                <SpeechToTextModelsProvider>
+                  <SpeechToTextPrewarm />
+                  <DiffViewerShell />
+                </SpeechToTextModelsProvider>
               </ConfigProvider>
             </ProviderProvider>
           </ServerProvider>
diff --git a/packages/kilo-vscode/webview-ui/diff-viewer/FullScreenDiffView.tsx b/packages/kilo-vscode/webview-ui/diff-viewer/FullScreenDiffView.tsx
index 73ba90e60f5..6f708f8bd91 100644
--- a/packages/kilo-vscode/webview-ui/diff-viewer/FullScreenDiffView.tsx
+++ b/packages/kilo-vscode/webview-ui/diff-viewer/FullScreenDiffView.tsx
@@ -27,6 +27,7 @@ import { useProvider } from "../src/context/provider"
 import { useConfig } from "../src/context/config"
 import { canUseSpeechToText, selectedSpeechToTextModel } from "../src/components/speech-to-text/availability"
 import { useSpeechToText } from "../src/components/speech-to-text/useSpeechToText"
+import { useSpeechToTextModels } from "../src/context/speech-to-text-models"
 import { FileTree } from "./FileTree"
 import { treeOrder } from "./file-tree-utils"
 import { getDirectory, getFilename, lineCount, sanitizeReviewComments, type ReviewComment } from "./review-comments"
@@ -113,8 +114,9 @@ export const FullScreenDiffView: Component<FullScreenDiffViewProps> = (props) =>
   const provider = useProvider()
   const { config } = useConfig()
   const speech = useSpeechToText(vscode, server, { t })
+  const speechModels = useSpeechToTextModels()
   const canUseSpeech = () => canUseSpeechToText(config(), provider.authStates())
-  const speechModel = () => selectedSpeechToTextModel(config())
+  const speechModel = () => selectedSpeechToTextModel(config(), speechModels.models())
   const isMac = typeof navigator !== "undefined" && /Mac|iPhone|iPad/.test(navigator.userAgent)
   const sendAllKeybind = () =>
     isMac ? t("agentManager.review.sendAllShortcut.mac") : t("agentManager.review.sendAllShortcut.other")
diff --git a/packages/kilo-vscode/webview-ui/src/components/chat/PromptInput.tsx b/packages/kilo-vscode/webview-ui/src/components/chat/PromptInput.tsx
index 530e4f89874..075b925b73b 100644
--- a/packages/kilo-vscode/webview-ui/src/components/chat/PromptInput.tsx
+++ b/packages/kilo-vscode/webview-ui/src/components/chat/PromptInput.tsx
@@ -10,6 +10,7 @@ import { Tooltip } from "@kilocode/kilo-ui/tooltip"
 import { FileIcon } from "@kilocode/kilo-ui/file-icon"
 import { Icon } from "@kilocode/kilo-ui/icon"
 import { showToast } from "@kilocode/kilo-ui/toast"
+import { isTextControl } from "../../utils/focus"
 import { useSession } from "../../context/session"
 import { useLocalTabs } from "../../context/local-tabs"
 import { useServer } from "../../context/server"
@@ -34,6 +35,7 @@ import { hasGitChangesMention } from "../../hooks/git-changes-context-utils"
 import { useSlashCommand } from "../../hooks/useSlashCommand"
 import { useGhostText } from "../../hooks/useGhostText"
 import { useSpeechToText } from "../speech-to-text/useSpeechToText"
+import { useSpeechToTextModels } from "../../context/speech-to-text-models"
 import { createSpeechShortcut } from "../speech-to-text/shortcut"
 import { useImageAttachments, type ImageAttachment } from "../../hooks/useImageAttachments"
 import { convertToMentionPath } from "../../utils/path-mentions"
@@ -348,6 +350,7 @@ export const PromptInput: Component<PromptInputProps> = (props) => {
 
   const ghost = useGhostText(vscode, text, () => server.isConnected())
   const speech = useSpeechToText(vscode, server, language)
+  const speechModels = useSpeechToTextModels()
 
   const replaceReviewComments = (next: ReviewComment[]) => {
     setReviewComments(next)
@@ -416,8 +419,12 @@ export const PromptInput: Component<PromptInputProps> = (props) => {
   const onFocusPrompt = (event: Event) => {
     const defer = () =>
       event instanceof CustomEvent && event.detail?.deferFocusToQuestion && props.deferFocusToQuestion?.()
+    const ownsFocus = () => {
+      const active = document.activeElement
+      return active !== textareaRef && isTextControl(active)
+    }
     const focus = () => {
-      if (defer()) return
+      if (defer() || ownsFocus()) return
       const ref = textareaRef
       if (!ref) return
       ref.focus({ preventScroll: true })
@@ -425,7 +432,7 @@ export const PromptInput: Component<PromptInputProps> = (props) => {
     focus()
     if (!(event instanceof CustomEvent) || !event.detail?.restore) return
     const restore = () => {
-      if (defer()) return
+      if (defer() || ownsFocus()) return
       window.focus()
       focus()
     }
@@ -511,7 +518,7 @@ export const PromptInput: Component<PromptInputProps> = (props) => {
     )
   const isDisabled = () => !server.isConnected()
   const canUseSpeech = () => canUseSpeechToText(config(), provider.authStates())
-  const speechModel = () => selectedSpeechToTextModel(config())
+  const speechModel = () => selectedSpeechToTextModel(config(), speechModels.models())
   const hasInput = () => text().trim().length > 0 || imageAttach.images().length > 0 || reviewComments().length > 0
   const canSend = () =>
     !isDisabled() &&
diff --git a/packages/kilo-vscode/webview-ui/src/components/settings/ModelsTab.tsx b/packages/kilo-vscode/webview-ui/src/components/settings/ModelsTab.tsx
index 81f57c39682..619cf17bd13 100644
--- a/packages/kilo-vscode/webview-ui/src/components/settings/ModelsTab.tsx
+++ b/packages/kilo-vscode/webview-ui/src/components/settings/ModelsTab.tsx
@@ -7,13 +7,14 @@ import { useConfig } from "../../context/config"
 import { useLanguage } from "../../context/language"
 import { useProvider } from "../../context/provider"
 import { useSession } from "../../context/session"
+import { useSpeechToTextModels } from "../../context/speech-to-text-models"
 import { parseModelString } from "../../../../src/shared/provider-model"
 import { ModelSelectorBase } from "../shared/ModelSelector"
 import { ThinkingSelectorBase } from "../shared/ThinkingSelector"
 import SettingsRow from "./SettingsRow"
 import { DEFAULT_SPEECH_TO_TEXT_MODEL } from "../../../../src/speech-to-text/models"
 import { hasSpeechToTextAccess, selectedSpeechToTextModel } from "../speech-to-text/availability"
-import { SPEECH_TO_TEXT_MODEL_OPTIONS } from "../speech-to-text/model-selector"
+import { speechToTextModelOptions } from "../speech-to-text/model-selector"
 import { AUTOCOMPLETE_SELECTOR_MODELS, getAutocompleteSelection } from "./autocomplete-model-selector"
 
 const ModelsTab: Component = () => {
@@ -21,6 +22,7 @@ const ModelsTab: Component = () => {
   const language = useLanguage()
   const provider = useProvider()
   const session = useSession()
+  const speechModels = useSpeechToTextModels()
 
   const autocompleteProvider = () => {
     const v = settings()["autocomplete.provider"]
@@ -42,8 +44,9 @@ const ModelsTab: Component = () => {
   }
 
   const subagentModel = createMemo(() => parseModelString(config().subagent_model ?? undefined))
-  const speechModel = createMemo(() => selectedSpeechToTextModel(config()))
-  const speechOption = createMemo(() => SPEECH_TO_TEXT_MODEL_OPTIONS.find((item) => item.value === speechModel()))
+  const speechModel = createMemo(() => selectedSpeechToTextModel(config(), speechModels.models()))
+  const speechOptions = createMemo(() => speechToTextModelOptions(speechModels.models()))
+  const speechOption = createMemo(() => speechOptions().find((item) => item.value === speechModel()))
   const kiloReady = createMemo(() => hasSpeechToTextAccess(config(), provider.authStates()))
   const variantKey = createMemo(() => config().subagent_model ?? undefined)
   const subagentVariants = createMemo(() => Object.keys(provider.findModel(subagentModel())?.variants ?? {}))
@@ -190,7 +193,7 @@ const ModelsTab: Component = () => {
             inactive={kiloReady()}
           >
             <Select
-              options={SPEECH_TO_TEXT_MODEL_OPTIONS}
+              options={speechOptions()}
               current={speechOption()}
               value={(item) => item.value}
               label={(item) => `${item.label} (${item.provider})`}
diff --git a/packages/kilo-vscode/webview-ui/src/components/speech-to-text/availability.ts b/packages/kilo-vscode/webview-ui/src/components/speech-to-text/availability.ts
index 3c386670b20..d25afa7bc99 100644
--- a/packages/kilo-vscode/webview-ui/src/components/speech-to-text/availability.ts
+++ b/packages/kilo-vscode/webview-ui/src/components/speech-to-text/availability.ts
@@ -1,5 +1,9 @@
 import { KILO_PROVIDER_ID } from "../../../../src/shared/provider-model"
-import { getSpeechToTextModel } from "../../../../src/speech-to-text/models"
+import {
+  DEFAULT_SPEECH_TO_TEXT_MODEL,
+  SPEECH_TO_TEXT_MODELS,
+  type SpeechToTextModelDef,
+} from "../../../../src/speech-to-text/models"
 
 type Cfg = {
   enabled_providers?: string[]
@@ -21,6 +25,10 @@ export function canUseSpeechToText(cfg: Cfg, auth: Readonly<Record<string, AuthS
   return hasSpeechToTextAccess(cfg, auth)
 }
 
-export function selectedSpeechToTextModel(cfg: Cfg): string {
-  return getSpeechToTextModel(cfg.experimental?.speech_to_text_model).id
+export function selectedSpeechToTextModel(
+  cfg: Cfg,
+  models: readonly SpeechToTextModelDef[] = SPEECH_TO_TEXT_MODELS,
+): string {
+  const id = cfg.experimental?.speech_to_text_model
+  return models.find((model) => model.id === id)?.id ?? models[0]?.id ?? DEFAULT_SPEECH_TO_TEXT_MODEL.id
 }
diff --git a/packages/kilo-vscode/webview-ui/src/components/speech-to-text/model-selector.ts b/packages/kilo-vscode/webview-ui/src/components/speech-to-text/model-selector.ts
index f91c258cb0a..be54aa4569e 100644
--- a/packages/kilo-vscode/webview-ui/src/components/speech-to-text/model-selector.ts
+++ b/packages/kilo-vscode/webview-ui/src/components/speech-to-text/model-selector.ts
@@ -1,4 +1,4 @@
-import { SPEECH_TO_TEXT_MODELS } from "../../../../src/speech-to-text/models"
+import type { SpeechToTextModelDef } from "../../../../src/speech-to-text/models"
 
 export type SpeechToTextModelOption = {
   value: string
@@ -6,8 +6,10 @@ export type SpeechToTextModelOption = {
   provider: string
 }
 
-export const SPEECH_TO_TEXT_MODEL_OPTIONS: SpeechToTextModelOption[] = SPEECH_TO_TEXT_MODELS.map((model) => ({
-  value: model.id,
-  label: model.label,
-  provider: model.provider,
-}))
+export function speechToTextModelOptions(models: readonly SpeechToTextModelDef[]): SpeechToTextModelOption[] {
+  return models.map((model) => ({
+    value: model.id,
+    label: model.label,
+    provider: model.provider,
+  }))
+}
diff --git a/packages/kilo-vscode/webview-ui/src/context/provider-shell.tsx b/packages/kilo-vscode/webview-ui/src/context/provider-shell.tsx
index 7a892052493..48ecd641c7c 100644
--- a/packages/kilo-vscode/webview-ui/src/context/provider-shell.tsx
+++ b/packages/kilo-vscode/webview-ui/src/context/provider-shell.tsx
@@ -23,6 +23,7 @@ import { NotificationsProvider } from "./notifications"
 import { FeedbackProvider } from "./feedback"
 import { KiloEmbeddingModelsProvider } from "./kilo-embedding-models"
 import { ImageModelsProvider } from "./image-models"
+import { SpeechToTextModelsProvider } from "./speech-to-text-models"
 import { SpeechToTextPrewarm } from "../components/speech-to-text/SpeechToTextPrewarm"
 
 type MermaidImageEvent = CustomEvent<{ dataUrl: string; filename: string }>
@@ -77,9 +78,11 @@ const Session: ParentComponent = (props) => (
   <IndexingProvider>
     <KiloEmbeddingModelsProvider>
       <ImageModelsProvider>
-        <NotificationsProvider>
-          <SessionProvider>{props.children}</SessionProvider>
-        </NotificationsProvider>
+        <SpeechToTextModelsProvider>
+          <NotificationsProvider>
+            <SessionProvider>{props.children}</SessionProvider>
+          </NotificationsProvider>
+        </SpeechToTextModelsProvider>
       </ImageModelsProvider>
     </KiloEmbeddingModelsProvider>
   </IndexingProvider>
diff --git a/packages/kilo-vscode/webview-ui/src/context/speech-to-text-models.tsx b/packages/kilo-vscode/webview-ui/src/context/speech-to-text-models.tsx
new file mode 100644
index 00000000000..1abc582347e
--- /dev/null
+++ b/packages/kilo-vscode/webview-ui/src/context/speech-to-text-models.tsx
@@ -0,0 +1,33 @@
+import { createContext, createSignal, onCleanup, useContext, type Accessor, type ParentComponent } from "solid-js"
+import { SPEECH_TO_TEXT_MODELS, type SpeechToTextModelDef } from "../../../src/speech-to-text/models"
+import { useVSCode } from "./vscode"
+import type { ExtensionMessage } from "../types/messages"
+
+export type SpeechToTextModelsContextValue = {
+  models: Accessor<readonly SpeechToTextModelDef[]>
+}
+
+export const SpeechToTextModelsContext = createContext<SpeechToTextModelsContextValue>({
+  models: () => SPEECH_TO_TEXT_MODELS,
+})
+
+export const SpeechToTextModelsProvider: ParentComponent = (props) => {
+  const vscode = useVSCode()
+  const [models, setModels] = createSignal<readonly SpeechToTextModelDef[]>([...SPEECH_TO_TEXT_MODELS])
+  const request = () => vscode.postMessage({ type: "requestSpeechToTextModels" })
+  const unsubscribe = vscode.onMessage((message: ExtensionMessage) => {
+    if (message.type !== "speechToTextModelsLoaded") return
+    setModels(message.models)
+  })
+
+  request()
+  const retry = setTimeout(request, 3000)
+  onCleanup(() => clearTimeout(retry))
+  onCleanup(unsubscribe)
+
+  return <SpeechToTextModelsContext.Provider value={{ models }}>{props.children}</SpeechToTextModelsContext.Provider>
+}
+
+export function useSpeechToTextModels(): SpeechToTextModelsContextValue {
+  return useContext(SpeechToTextModelsContext)
+}
diff --git a/packages/kilo-vscode/webview-ui/src/stories/tool-call-lab.stories.tsx b/packages/kilo-vscode/webview-ui/src/stories/tool-call-lab.stories.tsx
index b5f8d714d1d..995cfc705a7 100644
--- a/packages/kilo-vscode/webview-ui/src/stories/tool-call-lab.stories.tsx
+++ b/packages/kilo-vscode/webview-ui/src/stories/tool-call-lab.stories.tsx
@@ -180,6 +180,15 @@ const writePatch = [
   '+import { AssistantMessage } from "../components/chat/AssistantMessage"',
 ].join("\n")
 
+const tailPatch = [
+  "===================================================================",
+  "--- packages/kilo-vscode/webview-ui/src/components/chat/MessageList.tsx",
+  "+++ packages/kilo-vscode/webview-ui/src/components/chat/MessageList.tsx",
+  "@@ -1,1 +1,1 @@",
+  "-const old = true",
+  "+const next = true",
+].join("\n")
+
 const blockQuestions: QuestionRequest[] = [
   {
     id: "matrix-question-request",
@@ -465,7 +474,7 @@ const blocks: SDKPart[] = [
         "*** Begin Patch\n*** Update File: packages/kilo-ui/src/components/message-part.css\n@@\n-gap: 4px;\n+gap: 8px;\n*** End Patch",
     },
     output: "",
-    title: "Patch two files",
+    title: "Patch three files",
     metadata: {
       files: [
         {
@@ -486,6 +495,15 @@ const blocks: SDKPart[] = [
           additions: 1,
           deletions: 0,
         },
+        {
+          filePath: "/project/packages/kilo-vscode/webview-ui/src/components/chat/MessageList.tsx",
+          relativePath: "packages/kilo-vscode/webview-ui/src/components/chat/MessageList.tsx",
+          type: "update",
+          patch: tailPatch,
+          diff: tailPatch,
+          additions: 1,
+          deletions: 1,
+        },
       ],
     },
     time: { start: stamp - 2700, end: stamp - 2400 },
diff --git a/packages/kilo-vscode/webview-ui/src/types/messages/extension-messages.ts b/packages/kilo-vscode/webview-ui/src/types/messages/extension-messages.ts
index d7000fd4d08..d0fb0339252 100644
--- a/packages/kilo-vscode/webview-ui/src/types/messages/extension-messages.ts
+++ b/packages/kilo-vscode/webview-ui/src/types/messages/extension-messages.ts
@@ -19,6 +19,7 @@ import type { PermissionRequest } from "./permissions"
 import type { AnacondaDesktopExtensionMessage } from "../../../../src/shared/anaconda-desktop-messages"
 import type { QuestionRequest, SuggestionRequest, TodoItem } from "./questions"
 import type { ModelSelection, Provider, ProviderAuthState } from "./providers"
+import type { SpeechToTextModelDef } from "../../../../src/speech-to-text/models"
 import type { AgentInfo, AgentRequirementResult, SkillInfo, SlashCommandInfo } from "./agents"
 import type {
   BrowserSettings,
@@ -383,6 +384,11 @@ export interface ImageModelsLoadedMessage {
   models: Array<{ id: string; name: string; description?: string }>
 }
 
+export interface SpeechToTextModelsLoadedMessage {
+  type: "speechToTextModelsLoaded"
+  models: SpeechToTextModelDef[]
+}
+
 export interface ProvidersLoadedMessage {
   type: "providersLoaded"
   providers: Record<string, Provider>
@@ -894,6 +900,8 @@ export interface SandboxStatusErrorMessage {
 // Multi-version creation progress (extension → webview)
 export interface AgentManagerMultiVersionProgressMessage {
   type: "agentManager.multiVersionProgress"
+  /** Owning project; absent in single-project mode. */
+  projectId?: string
   status: "creating" | "done"
   total: number
   completed: number
@@ -1037,6 +1045,8 @@ export interface WorktreeStatsLoadedMessage {
 // Set the model for a session (extension → webview, used during multi-version creation)
 export interface AgentManagerSetSessionModelMessage {
   type: "agentManager.setSessionModel"
+  /** Owning project; absent in single-project mode. */
+  projectId?: string
   sessionId: string
   providerID: string
   modelID: string
@@ -1045,6 +1055,8 @@ export interface AgentManagerSetSessionModelMessage {
 // Request webview to send initial prompt to a newly created session (extension → webview)
 export interface AgentManagerSendInitialMessage {
   type: "agentManager.sendInitialMessage"
+  /** Owning project; absent in single-project mode. */
+  projectId?: string
   sessionId: string
   worktreeId: string
   text?: string
@@ -1301,6 +1313,7 @@ export type ExtensionMessage =
   | ChatSettingsLoadedMessage
   | KiloEmbeddingModelsLoadedMessage
   | ImageModelsLoadedMessage
+  | SpeechToTextModelsLoadedMessage
   | ProvidersLoadedMessage
   | AgentsLoadedMessage
   | SkillsLoadedMessage
diff --git a/packages/kilo-vscode/webview-ui/src/types/messages/webview-messages.ts b/packages/kilo-vscode/webview-ui/src/types/messages/webview-messages.ts
index 4f11b99d7c2..d4e1cf9a715 100644
--- a/packages/kilo-vscode/webview-ui/src/types/messages/webview-messages.ts
+++ b/packages/kilo-vscode/webview-ui/src/types/messages/webview-messages.ts
@@ -23,6 +23,7 @@ import type { MemoryShowMessage, MemoryOperationMessage, RequestMemoryMessage }
 
 export interface SendMessageRequest {
   type: "sendMessage"
+  projectId?: string
   text: string
   messageID?: string
   sessionID?: string
@@ -517,6 +518,10 @@ export interface RequestImageModelsMessage {
   type: "requestImageModels"
 }
 
+export interface RequestSpeechToTextModelsMessage {
+  type: "requestSpeechToTextModels"
+}
+
 export interface OpenSettingsTabRequest {
   type: "openSettingsTab"
   tab: string
@@ -1583,6 +1588,7 @@ export type WebviewMessage =
   | AgentManagerTerminalDestinationSelectedRequest
   | AgentManagerTerminalResizeRequest
   | RequestImageModelsMessage
+  | RequestSpeechToTextModelsMessage
 
 // ============================================
 // VS Code API type
diff --git a/packages/kilo-vscode/webview-ui/src/utils/focus.ts b/packages/kilo-vscode/webview-ui/src/utils/focus.ts
new file mode 100644
index 00000000000..a11abee27f9
--- /dev/null
+++ b/packages/kilo-vscode/webview-ui/src/utils/focus.ts
@@ -0,0 +1,9 @@
+const nonText = new Set(["button", "checkbox", "file", "hidden", "image", "radio", "range", "reset", "submit"])
+
+/** Whether an element owns editable text focus that should not be stolen. */
+export const isTextControl = (el: Element | null): boolean => {
+  if (!el) return false
+  if (el.tagName === "TEXTAREA" || el.tagName === "SELECT") return true
+  if (el.tagName === "INPUT") return !nonText.has((el as HTMLInputElement).type.toLowerCase())
+  return ("isContentEditable" in el && (el as HTMLElement).isContentEditable) || el.getAttribute("role") === "textbox"
+}
diff --git a/packages/kilo-web-ui/package.json b/packages/kilo-web-ui/package.json
index b0cc608f590..85f089d1046 100644
--- a/packages/kilo-web-ui/package.json
+++ b/packages/kilo-web-ui/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@kilocode/kilo-web-ui",
-  "version": "7.4.18",
+  "version": "7.4.20",
   "type": "module",
   "license": "MIT",
   "exports": {
diff --git a/packages/llm/package.json b/packages/llm/package.json
index f47683b9d24..7878a4f97aa 100644
--- a/packages/llm/package.json
+++ b/packages/llm/package.json
@@ -1,6 +1,6 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
-  "version": "7.4.18",
+  "version": "7.4.20",
   "name": "@opencode-ai/llm",
   "type": "module",
   "license": "MIT",
diff --git a/packages/opencode/CHANGELOG.md b/packages/opencode/CHANGELOG.md
index 42fac90936e..546437ee832 100644
--- a/packages/opencode/CHANGELOG.md
+++ b/packages/opencode/CHANGELOG.md
@@ -1,5 +1,44 @@
 # @kilocode/cli
 
+## 7.4.20
+
+### Patch Changes
+
+- [#12847](https://github.com/Kilo-Org/kilocode/pull/12847) [`9ed716a`](https://github.com/Kilo-Org/kilocode/commit/9ed716a5b8bc7b6f8546869b56f8bf0302f5de28) - Temporarily restore the default grep controls to prevent searches from stalling subagents.
+
+- [#12659](https://github.com/Kilo-Org/kilocode/pull/12659) [`39f65ef`](https://github.com/Kilo-Org/kilocode/commit/39f65efa8bc85490462b8a71ff0b7dddb1035d6a) Thanks [@mjnaderi](https://github.com/mjnaderi)! - Skip API and telemetry lifecycle work for informational CLI commands and avoid profile requests when telemetry is disabled.
+
+- [#11961](https://github.com/Kilo-Org/kilocode/pull/11961) [`fd60036`](https://github.com/Kilo-Org/kilocode/commit/fd60036e4a17f108c80d51221944c4200ba6b85c) Thanks [@mvanhorn](https://github.com/mvanhorn)! - Help models recover from invalid tool calls with clear, field-specific validation errors.
+
+- [#12846](https://github.com/Kilo-Org/kilocode/pull/12846) [`8c84f8a`](https://github.com/Kilo-Org/kilocode/commit/8c84f8ae5ef17a6e69a66cdd06680c6bf4e91db7) - Support project agent and command directory symlinks explicitly allowed by global Markdown source permissions.
+
+- Updated dependencies [[`39f65ef`](https://github.com/Kilo-Org/kilocode/commit/39f65efa8bc85490462b8a71ff0b7dddb1035d6a)]:
+  - @kilocode/kilo-telemetry@7.4.20
+
+## 7.4.19
+
+### Minor Changes
+
+- [#12728](https://github.com/Kilo-Org/kilocode/pull/12728) [`6b27a26`](https://github.com/Kilo-Org/kilocode/commit/6b27a26f929f570275e26529189b4d2fc3c392cf) Thanks [@bagatao-anaconda](https://github.com/bagatao-anaconda)! - Show why a tool call was auto-approved or denied in the TUI, and record the denial reason on the tool call metadata (visible in `kilo export`) alongside the existing auto-approval reason.
+
+- [#12816](https://github.com/Kilo-Org/kilocode/pull/12816) [`63a38f5`](https://github.com/Kilo-Org/kilocode/commit/63a38f5c7ae8fb08af1461b143a7c0f6b8dbc680) - A second identical large paste expands its collapsed prompt placeholder.
+
+- [#12729](https://github.com/Kilo-Org/kilocode/pull/12729) [`ce7984f`](https://github.com/Kilo-Org/kilocode/commit/ce7984fc4247fb2805990ef62e1b1d9f286de9d9) - Configure a model and reasoning variant for each workflow from Agent Behaviour settings.
+
+### Patch Changes
+
+- [#12792](https://github.com/Kilo-Org/kilocode/pull/12792) [`7d3f50c`](https://github.com/Kilo-Org/kilocode/commit/7d3f50c2e8510e6ae86bb310c2706bb79f1c02ff) - Prevent configured compaction thresholds from interrupting active tool sequences.
+
+- [#12652](https://github.com/Kilo-Org/kilocode/pull/12652) [`c554409`](https://github.com/Kilo-Org/kilocode/commit/c554409080a59422066f93df90155e448ec9b250) Thanks [@Hardik180704](https://github.com/Hardik180704)! - Keep config-defined subagents routable when an installed primary agent uses the same name.
+
+- [#12726](https://github.com/Kilo-Org/kilocode/pull/12726) [`2fbd380`](https://github.com/Kilo-Org/kilocode/commit/2fbd380dfcfcbc4537e48727b15af2176451cf84) - Speed up local session recall searches across large conversation histories.
+
+- [#12811](https://github.com/Kilo-Org/kilocode/pull/12811) [`989f7f0`](https://github.com/Kilo-Org/kilocode/commit/989f7f06a03f3502e7ab761f1ae72b5c7b47451c) - Add bounded, context-aware signal-to-noise controls to grep searches.
+
+- [#12790](https://github.com/Kilo-Org/kilocode/pull/12790) [`8be3303`](https://github.com/Kilo-Org/kilocode/commit/8be33032b906f27c0d883212354f75eeb7044f35) - Keep Kilo's persona out of generated conversation titles and Agent Manager branch names.
+
+- [#12802](https://github.com/Kilo-Org/kilocode/pull/12802) [`5bd420a`](https://github.com/Kilo-Org/kilocode/commit/5bd420aae15787dc629d27b663f9f1b6e2cac888) Thanks [@bagatao-anaconda](https://github.com/bagatao-anaconda)! - Stop treating `` !`cmd` `` shown as an inline code example in skill documentation as a live command, so it no longer triggers a shell permission prompt.
+
 ## 7.4.18
 
 ### Minor Changes
diff --git a/packages/opencode/package.json b/packages/opencode/package.json
index ea7b37fb09d..87942df31df 100644
--- a/packages/opencode/package.json
+++ b/packages/opencode/package.json
@@ -1,6 +1,6 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
-  "version": "7.4.18",
+  "version": "7.4.20",
   "name": "@kilocode/cli",
   "type": "module",
   "license": "MIT",
diff --git a/packages/opencode/script/kilocode/npm-publish.ts b/packages/opencode/script/kilocode/npm-publish.ts
index 8f07ed2e750..2744ff675e4 100644
--- a/packages/opencode/script/kilocode/npm-publish.ts
+++ b/packages/opencode/script/kilocode/npm-publish.ts
@@ -3,10 +3,6 @@ export namespace NpmPublish {
   const base = 10_000
   const jitter = 5_000
 
-  export function aliases(channel: string) {
-    return channel === "latest" ? ["rc"] : []
-  }
-
   export async function retry(input: {
     name: string
     version: string
diff --git a/packages/opencode/script/publish.ts b/packages/opencode/script/publish.ts
index cfc99cacabd..bd94c7c0e3e 100755
--- a/packages/opencode/script/publish.ts
+++ b/packages/opencode/script/publish.ts
@@ -16,21 +16,18 @@ async function publish(dir: string, name: string, version: string) {
   // GitHub artifact downloads can drop the executable bit, and Docker uses the
   // unpacked dist binaries directly rather than the published tarball.
   if (process.platform !== "win32") await $`chmod -R 755 .`.cwd(dir)
-  // kilocode_change start
-  const exists = await published(name, version)
-  if (exists) {
+  if (await published(name, version)) {
     console.log(`already published ${name}@${version}`)
+    return
   }
-  if (!exists) {
-    await $`bun pm pack`.cwd(dir)
-    await NpmPublish.retry({
-      name,
-      version,
-      run: () => $`npm publish *.tgz --access public --tag ${Script.channel} --provenance`.cwd(dir),
-      exists: () => published(name, version),
-    })
-  }
-  for (const tag of NpmPublish.aliases(Script.channel)) await $`npm dist-tag add ${name}@${version} ${tag}`
+  await $`bun pm pack`.cwd(dir)
+  // kilocode_change start
+  await NpmPublish.retry({
+    name,
+    version,
+    run: () => $`npm publish *.tgz --access public --tag ${Script.channel} --provenance`.cwd(dir),
+    exists: () => published(name, version),
+  })
   // kilocode_change end
 }
 
diff --git a/packages/opencode/src/command/index.ts b/packages/opencode/src/command/index.ts
index 332b2e5c872..fc7661977ec 100644
--- a/packages/opencode/src/command/index.ts
+++ b/packages/opencode/src/command/index.ts
@@ -11,6 +11,7 @@ import { legacyReviewCommand, reviewCommand } from "@/kilocode/review/command" /
 import { apply as applyOverride, type Override } from "@/kilocode/command/override" // kilocode_change
 import { EventV2 } from "@opencode-ai/core/event"
 import PROMPT_INITIALIZE from "./template/initialize.txt"
+import { SessionResume } from "@/kilocode/session-resume" // kilocode_change
 
 type State = {
   commands: Record<string, Info>
@@ -114,6 +115,8 @@ export const layer = Layer.effect(
       commands[Default.REVIEW] = reviewCommand()
       commands["local-review"] = legacyReviewCommand("local-review")!
       commands["local-review-uncommitted"] = legacyReviewCommand("local-review-uncommitted")!
+      commands["resume-claude"] = SessionResume.resumeClaude
+      commands["resume-codex"] = SessionResume.resumeCodex
       // kilocode_change end
 
       // kilocode_change start - defer partial overrides until all command sources are registered
diff --git a/packages/opencode/src/config/agent.ts b/packages/opencode/src/config/agent.ts
index 7aa4430b728..31f898e82cd 100644
--- a/packages/opencode/src/config/agent.ts
+++ b/packages/opencode/src/config/agent.ts
@@ -24,7 +24,7 @@ export async function load(
   warnings?: Warning[],
   trusted = false,
   fileScope?: ConfigVariable.FileScope,
-  sourceScope?: ConfigVariable.FileScope,
+  sourceScope?: ConfigVariable.FileScope | readonly ConfigVariable.FileScope[],
 ) {
   // kilocode_change end
   const result: Record<string, ConfigAgentV1.Info> = {}
diff --git a/packages/opencode/src/config/command.ts b/packages/opencode/src/config/command.ts
index 36d40be13f7..fe29288d2d4 100644
--- a/packages/opencode/src/config/command.ts
+++ b/packages/opencode/src/config/command.ts
@@ -25,7 +25,7 @@ export async function load(
   warnings?: Warning[],
   trusted = false,
   fileScope?: ConfigVariable.FileScope,
-  sourceScope?: ConfigVariable.FileScope,
+  sourceScope?: ConfigVariable.FileScope | readonly ConfigVariable.FileScope[],
 ) {
   // kilocode_change end
   const result: Record<string, ConfigCommandV1.Info> = {}
diff --git a/packages/opencode/src/config/config.ts b/packages/opencode/src/config/config.ts
index cdd433b92ab..7ce0b002e4d 100644
--- a/packages/opencode/src/config/config.ts
+++ b/packages/opencode/src/config/config.ts
@@ -47,6 +47,7 @@ import { Git } from "@/git"
 import { KilocodeDefaultPlugins } from "@/kilocode/config/default-plugins"
 import { KilocodeGlobalConfigStamp } from "@/kilocode/config/global-stamp"
 import { SandboxConfig } from "@/kilocode/sandbox/config"
+import { ExternalMarkdown } from "@/kilocode/config/external-markdown"
 import type { KilocodeMarkdown } from "@/kilocode/config/markdown"
 import {
   IndexingConfig as KiloIndexingConfig,
@@ -763,13 +764,26 @@ export const layer = Layer.effect(
           deps.push(dep)
 
           // kilocode_change start - propagate parse errors to the Warning accumulator
+          const sourceScopes = (names: readonly string[]) => [
+            ...(dirSourceScope ? [dirSourceScope] : []),
+            ...ExternalMarkdown.scopes({
+              dir,
+              names,
+              permission: result.permission,
+              origins: result.permission_origins,
+            }),
+          ]
           result.command = mergeDeep(
             result.command ?? {},
-            yield* Effect.promise(() => ConfigCommand.load(dir, warnings, dirTrusted, dirFileScope, dirSourceScope)),
+            yield* Effect.promise(() =>
+              ConfigCommand.load(dir, warnings, dirTrusted, dirFileScope, sourceScopes(["command", "commands"])),
+            ),
           )
           result.agent = KilocodeConfig.mergeAgentMarkdown(
             result.agent ?? {},
-            yield* Effect.promise(() => ConfigAgent.load(dir, warnings, dirTrusted, dirFileScope, dirSourceScope)),
+            yield* Effect.promise(() =>
+              ConfigAgent.load(dir, warnings, dirTrusted, dirFileScope, sourceScopes(["agent", "agents"])),
+            ),
             configuredAgents,
           )
           result.agent = KilocodeConfig.mergeAgentMarkdown(
diff --git a/packages/opencode/src/index.ts b/packages/opencode/src/index.ts
index 1da9d9d9c89..779f51423af 100644
--- a/packages/opencode/src/index.ts
+++ b/packages/opencode/src/index.ts
@@ -81,7 +81,7 @@ let cli = yargs(args) // kilocode_change
     process.env.AGENT = "1"
     process.env.OPENCODE = "1"
     process.env.KILO_PID = String(process.pid)
-    await KiloCli.bootstrap() // kilocode_change - env tagging, telemetry init, legacy JSON-to-SQLite migration, and auth migration
+    await KiloCli.bootstrap(opts) // kilocode_change - env tagging, telemetry init, legacy JSON-to-SQLite migration, and auth migration
     // kilocode_change start - retain Kilo process/run correlation metadata in startup logs
     Log.Default.info("opencode", {
       version: InstallationVersion,
diff --git a/packages/opencode/src/kilocode/cli/setup.ts b/packages/opencode/src/kilocode/cli/setup.ts
index e3c54c3065b..fd14af0f88f 100644
--- a/packages/opencode/src/kilocode/cli/setup.ts
+++ b/packages/opencode/src/kilocode/cli/setup.ts
@@ -43,6 +43,8 @@ KiloShutdown.register(async () => {
 // in opencode#30453. The registered command modules must follow the same rule: a light
 // top level, with implementation imports inside their handlers.
 export namespace KiloCli {
+  let info = false
+
   // Register only the Kilo-specific commands. Upstream commands stay in index.ts's chain so
   // upstream merges that add or remove commands keep working without touching this file.
   export function register<T>(cli: Argv<T>): Argv<T> {
@@ -69,7 +71,10 @@ export namespace KiloCli {
 
   // Runs from the upstream `.middleware`, before any command handler. Env tagging is additive so
   // it never has to modify upstream's own env assignments.
-  export async function bootstrap(): Promise<void> {
+  export async function bootstrap(opts: { [key: string]: unknown }): Promise<void> {
+    info = opts.help === true || opts.version === true
+    if (info) return
+
     const { KiloLog } = await import("@/kilocode/log")
     await KiloLog.init()
 
@@ -120,6 +125,7 @@ export namespace KiloCli {
 
   // Runs from the `finally` block on every exit path.
   export async function shutdown(): Promise<void> {
+    if (info) return
     const { Telemetry } = await import("@kilocode/kilo-telemetry")
     const code = typeof process.exitCode === "number" ? process.exitCode : undefined
     Telemetry.trackCliExit(code)
diff --git a/packages/opencode/src/kilocode/config/external-markdown.ts b/packages/opencode/src/kilocode/config/external-markdown.ts
new file mode 100644
index 00000000000..c8b75381c85
--- /dev/null
+++ b/packages/opencode/src/kilocode/config/external-markdown.ts
@@ -0,0 +1,66 @@
+import { realpathSync } from "node:fs"
+import os from "node:os"
+import path from "node:path"
+import type { ConfigPermissionV1 } from "@opencode-ai/core/v1/config/permission"
+import type { ConfigVariableGuard } from "./variable"
+
+export namespace ExternalMarkdown {
+  type Origins = Record<string, Record<string, "global" | "local">>
+
+  function expand(pattern: string) {
+    if (pattern.startsWith("~/")) return os.homedir() + pattern.slice(1)
+    if (pattern === "~") return os.homedir()
+    if (pattern.startsWith("$HOME/")) return os.homedir() + pattern.slice(5)
+    if (pattern.startsWith("$HOME")) return os.homedir() + pattern.slice(5)
+    return pattern
+  }
+
+  function normalize(value: string) {
+    const result = path.normalize(value)
+    return process.platform === "win32" ? result.toLowerCase() : result
+  }
+
+  function bounded(pattern: string, root: string) {
+    const value = expand(pattern).replaceAll("\\", "/")
+    const index = value.search(/[?*]/)
+    if (index === -1) return false
+    const prefix = value.slice(0, index).replace(/\/+$/, "")
+    if (!path.isAbsolute(prefix) || value.slice(prefix.length) !== "/*") return false
+    try {
+      return normalize(realpathSync.native(prefix)) === normalize(root)
+    } catch {
+      return false
+    }
+  }
+
+  function allowed(root: string, permission: ConfigPermissionV1.Info | undefined, origins: Origins | undefined) {
+    const rule = permission?.markdown_source
+    if (!rule || typeof rule === "string") return false
+    const winner = Object.entries(rule)
+      .filter(([, action]) => action !== null)
+      .findLast(([pattern]) => bounded(pattern, root))
+    if (!winner || origins?.markdown_source?.[winner[0]] !== "global") return false
+    return winner[1] === "allow"
+  }
+
+  export function scopes(input: {
+    dir: string
+    names: readonly string[]
+    permission: ConfigPermissionV1.Info | undefined
+    origins: Origins | undefined
+  }): ConfigVariableGuard.FileScope[] {
+    const result: ConfigVariableGuard.FileScope[] = []
+    for (const name of input.names) {
+      const source = path.join(input.dir, name)
+      try {
+        const root = realpathSync.native(source)
+        if (normalize(root) === normalize(source)) continue
+        if (!allowed(root, input.permission, input.origins)) continue
+        result.push({ root, source })
+      } catch {
+        continue
+      }
+    }
+    return result
+  }
+}
diff --git a/packages/opencode/src/kilocode/config/markdown.ts b/packages/opencode/src/kilocode/config/markdown.ts
index 3b32c774dbf..ff7fbe34053 100644
--- a/packages/opencode/src/kilocode/config/markdown.ts
+++ b/packages/opencode/src/kilocode/config/markdown.ts
@@ -2,6 +2,7 @@ import { ConfigVariable } from "@/config/variable"
 import { InvalidError } from "@opencode-ai/core/v1/config/error"
 import { Filesystem } from "@/util/filesystem"
 import { ConfigVariableGuard } from "./variable"
+import path from "node:path"
 
 export namespace KilocodeMarkdown {
   export type Source = {
@@ -13,12 +14,17 @@ export namespace KilocodeMarkdown {
   export type Options = {
     trusted: boolean
     fileScope?: ConfigVariable.FileScope
-    sourceScope?: ConfigVariable.FileScope
+    sourceScope?: ConfigVariable.FileScope | readonly ConfigVariable.FileScope[]
   }
 
   export function read(item: string, options: Options) {
     if (options.trusted) return Filesystem.readText(item)
-    const scope = options.sourceScope ?? options.fileScope
+    const scope = Array.isArray(options.sourceScope)
+      ? options.sourceScope.findLast((scope) => {
+          const rel = path.relative(scope.source, item)
+          return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel))
+        })
+      : (options.sourceScope ?? options.fileScope)
     if (!scope) {
       throw new InvalidError({
         path: item,
diff --git a/packages/opencode/src/kilocode/server/httpapi/groups/kilo-gateway.ts b/packages/opencode/src/kilocode/server/httpapi/groups/kilo-gateway.ts
index 9e0068cbaba..f77ad9c077a 100644
--- a/packages/opencode/src/kilocode/server/httpapi/groups/kilo-gateway.ts
+++ b/packages/opencode/src/kilocode/server/httpapi/groups/kilo-gateway.ts
@@ -218,6 +218,11 @@ export const ImageModel = Schema.Struct({
   description: Schema.optional(Schema.String),
 })
 
+export const TranscriptionModel = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String,
+})
+
 const UnknownRecord = Schema.Record(Schema.String, Schema.Unknown)
 
 export const CloudMessage = Schema.StructWithRest(
@@ -272,6 +277,7 @@ export const KiloGatewayPaths = {
   edit: `${root}/edit`,
   audioTranscriptions: `${root}/audio/transcriptions`,
   imageModels: `${root}/models/images`,
+  transcriptionModels: `${root}/models/transcriptions`,
   notifications: `${root}/notifications`,
   organization: `${root}/organization`,
   clawStatus: `${root}/claw/status`,
@@ -366,6 +372,17 @@ export const KiloGatewayApi = HttpApi.make("kilo")
             description: "List image-capable models from the Kilo Gateway OpenRouter passthrough",
           }),
         ),
+        HttpApiEndpoint.get("transcriptionModels", KiloGatewayPaths.transcriptionModels, {
+          query: WorkspaceRoutingQuery,
+          success: described(Schema.Array(TranscriptionModel), "Speech-to-text model list"),
+          error: [HttpApiError.BadRequest, HttpApiError.Unauthorized],
+        }).annotateMerge(
+          OpenApi.annotations({
+            identifier: "kilo.models.transcriptions",
+            summary: "Speech-to-text models",
+            description: "List transcription-capable models from the Kilo Gateway catalog",
+          }),
+        ),
         HttpApiEndpoint.get("notifications", KiloGatewayPaths.notifications, {
           query: WorkspaceRoutingQuery,
           success: described(Schema.Array(Notification), "Notifications list"),
diff --git a/packages/opencode/src/kilocode/server/httpapi/handlers/kilo-gateway.ts b/packages/opencode/src/kilocode/server/httpapi/handlers/kilo-gateway.ts
index dac2ebca8ee..7ed634101c9 100644
--- a/packages/opencode/src/kilocode/server/httpapi/handlers/kilo-gateway.ts
+++ b/packages/opencode/src/kilocode/server/httpapi/handlers/kilo-gateway.ts
@@ -5,6 +5,7 @@ import {
   fetchCloudSession,
   fetchCloudSessionForImport,
   fetchKiloImageModels,
+  fetchKiloTranscriptionModels,
   getCloudSessions,
   getOrganizationId,
   getToken,
@@ -614,6 +615,29 @@ export const kiloGatewayHandlers = HttpApiBuilder.group(InstanceHttpApi, "kilo",
       return result.models
     })
 
+    const transcriptionModels = Effect.fn("KiloGatewayHttpApi.transcriptionModels")(function* () {
+      const info = yield* proxyAuth()
+      if (!info.auth) return yield* Effect.fail(new HttpApiError.Unauthorized({}))
+      if (!info.token) return yield* Effect.fail(new HttpApiError.Unauthorized({}))
+
+      const result = yield* Effect.tryPromise({
+        try: () =>
+          fetchKiloTranscriptionModels({
+            kilocodeToken: info.token,
+            kilocodeOrganizationId: info.organizationId,
+          }),
+        catch: () => new HttpApiError.BadRequest({}),
+      })
+
+      if (result.error) {
+        const err =
+          result.error.kind === "unauthorized" ? new HttpApiError.Unauthorized({}) : new HttpApiError.BadRequest({})
+        return yield* Effect.fail(err)
+      }
+
+      return result.models
+    })
+
     return handlers
       .handle("profile", profile)
       .handle("authStatus", authStatus)
@@ -622,6 +646,7 @@ export const kiloGatewayHandlers = HttpApiBuilder.group(InstanceHttpApi, "kilo",
       .handle("edit", edit)
       .handle("audioTranscriptions", audioTranscriptions)
       .handle("imageModels", imageModels)
+      .handle("transcriptionModels", transcriptionModels)
       .handle("notifications", notifications)
       .handle("organization", organization)
       .handle("clawStatus", clawStatus)
diff --git a/packages/opencode/src/kilocode/session-resume/index.ts b/packages/opencode/src/kilocode/session-resume/index.ts
new file mode 100644
index 00000000000..62062a60f7a
--- /dev/null
+++ b/packages/opencode/src/kilocode/session-resume/index.ts
@@ -0,0 +1,1136 @@
+import fs from "node:fs"
+import os from "node:os"
+import path from "node:path"
+import * as readline from "node:readline"
+import { Context } from "effect"
+
+export namespace SessionResume {
+  export const SUPPORTED_CLAUDE_MAJOR = 2
+  export const SUPPORTED_CODEX_MAJOR = 0
+
+  export type Format = "claude" | "codex"
+
+  // ── Test-only resume roots ──────────────────────────────────────────
+
+  export type HarnessRoots = {
+    claude?: string
+    codex?: string
+  }
+
+  /** Test-only seam to redirect transcript discovery roots.
+   *  Not available through the public command API. */
+  export class ResumeRoots extends Context.Service<ResumeRoots, HarnessRoots>()("SessionResume.ResumeRoots") {}
+
+  // ── UUID ───────────────────────────────────────────────────────────
+
+  const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+  export function isUUID(id: string): boolean {
+    return UUID_RE.test(id)
+  }
+
+  export function validateUUID(id: string): void {
+    if (!isUUID(id)) throw new ParseError(`Invalid UUID: ${id}`)
+  }
+
+  // ── Parsed parts ──────────────────────────────────────────────────
+
+  export type TextPart = {
+    type: "text"
+    text: string
+  }
+
+  export type ReasoningPart = {
+    type: "reasoning"
+    text: string
+  }
+
+  export type ToolCall = {
+    type: "tool_call"
+    id: string
+    name: string
+    input: unknown
+    status?: "failed" | "error" | "incomplete"
+  }
+
+  export type ToolResult = {
+    type: "tool_result"
+    callID: string
+    content: string
+    error?: boolean
+  }
+
+  export type Unsupported = {
+    type: "unsupported"
+    reason: string
+  }
+
+  export type ErrorPart = {
+    type: "error"
+    message: string
+  }
+
+  export type Part = TextPart | ReasoningPart | ToolCall | ToolResult | Unsupported | ErrorPart
+
+  // ── Steps and transcript ──────────────────────────────────────────
+
+  export type Step = {
+    role: "user" | "assistant"
+    parts: Part[]
+  }
+
+  export type Transcript = {
+    format: Format
+    version: number
+    steps: Step[]
+    unsupported: number
+    sourceModel?: { providerID: string; modelID: string }
+  }
+
+  // ── Errors ────────────────────────────────────────────────────────
+
+  export class ParseError extends Error {
+    constructor(
+      message: string,
+      public override cause?: unknown,
+    ) {
+      super(message)
+      this.name = "SessionResumeParseError"
+    }
+  }
+
+  // ── Helpers ───────────────────────────────────────────────────────
+
+  function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+  }
+
+  function isArray(value: unknown): value is unknown[] {
+    return Array.isArray(value)
+  }
+
+  function safeParse(line: string): unknown {
+    try {
+      return JSON.parse(line)
+    } catch {
+      return undefined
+    }
+  }
+
+  // ── Detection ─────────────────────────────────────────────────────
+
+  /** Detect whether a parsed JSON line belongs to a Claude or Codex session. */
+  export function detect(line: unknown): Format | undefined {
+    if (!isRecord(line)) return undefined
+
+    const type = line.type
+
+    // Claude: top-level type is "user" or "assistant" + message.{role,content}
+    if ((type === "user" || type === "assistant") && isRecord(line.message)) {
+      const msg = line.message as Record<string, unknown>
+      if (typeof msg.role === "string" && (isArray(msg.content) || typeof msg.content === "string")) {
+        return "claude"
+      }
+    }
+
+    // Codex: type is session_meta or response_item
+    if (type === "session_meta" || type === "response_item") {
+      return "codex"
+    }
+
+    return undefined
+  }
+
+  // ── Discovery ─────────────────────────────────────────────────────
+
+  /** List JSONL files under a directory (non-recursive). */
+  export function discover(dir: string): string[] {
+    const entries = fs.readdirSync(dir, { withFileTypes: true })
+    return entries
+      .filter((e) => e.isFile() && e.name.endsWith(".jsonl"))
+      .map((e) => path.join(dir, e.name))
+  }
+
+  export type DiscoveryInput = HarnessRoots & {
+    cwd: string
+    id?: string
+  }
+
+  export function claudeProjectSlug(cwd: string): string {
+    return cwd.replace(/[^A-Za-z0-9-]/g, "-")
+  }
+
+  function roots(input: HarnessRoots) {
+    return {
+      claude: input.claude ?? path.join(os.homedir(), ".claude", "projects"),
+      codex: input.codex ?? path.join(os.homedir(), ".codex", "sessions"),
+    }
+  }
+
+  export function discoverClaude(input: DiscoveryInput): string[] {
+    const root = roots(input).claude
+    const directory = path.join(root, claudeProjectSlug(input.cwd))
+    if (input.id) {
+      validateUUID(input.id)
+      const file = path.join(directory, `${input.id}.jsonl`)
+      const stat = fs.statSync(file)
+      if (!stat.isFile()) throw new ParseError(`Unreadable Claude transcript: ${input.id}`)
+      return [file]
+    }
+    return discover(directory)
+      .filter((file) => isUUID(path.basename(file, ".jsonl")))
+      .map((file) => ({ file, time: fs.statSync(file).mtimeMs }))
+      .sort((a, b) => b.time - a.time)
+      .slice(0, 10)
+      .map((entry) => entry.file)
+  }
+
+  export async function discoverCodex(input: DiscoveryInput): Promise<string[]> {
+    const root = roots(input).codex
+    if (input.id) validateUUID(input.id)
+    const files: { file: string; time: string }[] = []
+    const matches = new Set<string>()
+    for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+      if (entry.isFile() && entry.name.startsWith("rollout-") && entry.name.endsWith(".jsonl")) matches.add(entry.name)
+    }
+    for await (const relative of new Bun.Glob("**/rollout-*.jsonl").scan({ cwd: root, onlyFiles: true })) {
+      matches.add(relative)
+    }
+    for (const relative of matches) {
+      if (input.id && !relative.endsWith(`-${input.id}.jsonl`)) continue
+      const file = path.join(root, relative)
+      if (!input.id) {
+        let first: unknown
+        try {
+          first = await readFirstJSONL(file)
+        } catch {
+          continue
+        }
+        if (!isRecord(first) || first.type !== "session_meta" || !isRecord(first.payload)) continue
+        if (first.payload.cwd !== input.cwd) continue
+      }
+      files.push({ file, time: path.basename(file).slice("rollout-".length, 38) })
+    }
+    return files
+      .sort((a, b) => b.time.localeCompare(a.time))
+      .slice(0, 10)
+      .map((entry) => entry.file)
+  }
+
+  // ── Format auto-detection from objects ────────────────────────────
+
+  function detectFormat(objects: unknown[]): Format {
+    for (const obj of objects) {
+      const fmt = detect(obj)
+      if (fmt) return fmt
+    }
+    throw new ParseError("Unrecognized session format")
+  }
+
+  // ── Parse entry ───────────────────────────────────────────────────
+
+  /** Parse a JSONL file into a transcript. Uses node:readline streaming. */
+  export async function parse(filepath: string): Promise<Transcript> {
+    const objects = await readJSONL(filepath)
+    if (objects.length === 0) throw new ParseError("Empty input")
+    return parseObjects(objects)
+  }
+
+  /** Parse raw JSONL text into a transcript (for testing). */
+  export function parseLines(text: string): Transcript {
+    const trimmed = text.trim()
+    if (trimmed.length === 0) throw new ParseError("Empty input")
+
+    const objects: unknown[] = []
+    const lines = trimmed.split("\n")
+
+    for (const [i, raw] of lines.entries()) {
+      const line = raw.trim()
+      if (line.length === 0) continue
+      const parsed = safeParse(line)
+      if (parsed === undefined) throw new ParseError(`Line ${i + 1}: invalid JSON`)
+      objects.push(parsed)
+    }
+
+    if (objects.length === 0) throw new ParseError("No valid JSON Lines found")
+    return parseObjects(objects)
+  }
+
+  // ── Streaming read ────────────────────────────────────────────────
+
+  async function readJSONL(filepath: string): Promise<unknown[]> {
+    const objects: unknown[] = []
+    const stream = fs.createReadStream(filepath, "utf-8")
+    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity })
+    let lineNum = 0
+    let failure: ParseError | undefined
+
+    return new Promise<unknown[]>((resolve, reject) => {
+      rl.on("line", (raw: string) => {
+        lineNum++
+        const line = raw.trim()
+        if (line.length === 0) return
+        const parsed = safeParse(line)
+        if (parsed === undefined) {
+          failure = new ParseError(`Line ${lineNum}: invalid JSON`)
+          rl.close()
+          return
+        }
+        objects.push(parsed)
+      })
+      rl.on("close", () => {
+        if (failure) reject(failure)
+        else resolve(objects)
+      })
+      rl.on("error", (err) => reject(new ParseError("Failed to read file", err)))
+    })
+  }
+
+  async function readFirstJSONL(filepath: string): Promise<unknown> {
+    const stream = fs.createReadStream(filepath, "utf-8")
+    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity })
+    try {
+      for await (const raw of rl) {
+        const line = raw.trim()
+        if (line) return safeParse(line)
+      }
+      return undefined
+    } finally {
+      rl.close()
+      stream.destroy()
+    }
+  }
+
+  // ── Parse objects ─────────────────────────────────────────────────
+
+  function parseObjects(objects: unknown[]): Transcript {
+    const format = detectFormat(objects)
+
+    if (format === "claude") {
+      const version = readClaudeVersion(objects)
+      if (version !== SUPPORTED_CLAUDE_MAJOR) {
+        throw new ParseError(`Unsupported Claude major version: ${version}`)
+      }
+      const model = extractClaudeModel(objects)
+      const { steps, unsupported } = parseClaudeSteps(objects)
+      return { format, version, steps, unsupported, sourceModel: model }
+    }
+
+    const version = readCodexVersion(objects)
+    if (version === undefined) {
+      throw new ParseError("Missing session_meta record in Codex transcript")
+    }
+    if (version !== SUPPORTED_CODEX_MAJOR) {
+      throw new ParseError(`Unsupported Codex major version: ${version}`)
+    }
+    const model = extractCodexModel(objects)
+    const { steps, unsupported } = parseCodexSteps(objects)
+    return { format, version, steps, unsupported, sourceModel: model }
+  }
+
+  // ── Version reading ───────────────────────────────────────────────
+
+  function readClaudeVersion(objects: unknown[]): number {
+    for (const obj of objects) {
+      if (!isRecord(obj)) continue
+      const topType = obj.type
+      if (topType !== "user" && topType !== "assistant") continue
+      const ver = obj.version
+      if (typeof ver === "string") {
+        const major = parseInt(ver.split(".")[0], 10)
+        if (!isNaN(major)) return major
+      }
+      // Version field missing or unparseable on a user/assistant record
+      throw new ParseError("Claude record missing version field")
+    }
+    throw new ParseError("No Claude user or assistant records found")
+  }
+
+  function readCodexVersion(objects: unknown[]): number | undefined {
+    for (const obj of objects) {
+      if (!isRecord(obj) || obj.type !== "session_meta") continue
+      const payload = obj.payload
+      if (!isRecord(payload)) continue
+      const cliVer = payload.cli_version
+      const verStr = typeof cliVer === "string" ? cliVer : (isRecord(cliVer) ? String(cliVer.major ?? "") : "")
+      if (verStr.length === 0) continue
+      const major = parseInt(verStr.split(".")[0], 10)
+      if (!isNaN(major)) return major
+    }
+  }
+
+  function extractClaudeModel(objects: unknown[]): { providerID: string; modelID: string } | undefined {
+    for (const obj of objects) {
+      if (!isRecord(obj)) continue
+      const topType = obj.type
+      if (topType !== "user" && topType !== "assistant") continue
+      const message = obj.message
+      if (!isRecord(message)) continue
+      const model = message.model
+      if (typeof model === "string" && model.length > 0) {
+        return { providerID: "anthropic", modelID: model }
+      }
+    }
+  }
+
+  function extractCodexModel(objects: unknown[]): { providerID: string; modelID: string } | undefined {
+    let provider: string | undefined
+    let model: string | undefined
+
+    for (const obj of objects) {
+      if (!isRecord(obj)) continue
+
+      if (obj.type === "session_meta") {
+        const payload = obj.payload
+        if (!isRecord(payload)) continue
+        const mp = payload.model_provider
+        if (typeof mp === "string" && mp.length > 0) provider = mp
+      }
+
+      if (obj.type === "turn_context") {
+        const payload = obj.payload
+        if (!isRecord(payload)) continue
+        const m = payload.model
+        if (typeof m === "string" && m.length > 0) model = m
+      }
+    }
+
+    if (provider && model) return { providerID: provider, modelID: model }
+  }
+
+  // ── Tool call error marking ────────────────────────────────────────
+
+  function markUnpaired(step: Step): Step {
+    const toolCalls = step.parts.filter((p): p is ToolCall => p.type === "tool_call")
+    const resultIDs = new Set(
+      step.parts.filter((p): p is ToolResult => p.type === "tool_result").map((r) => r.callID),
+    )
+    for (const tc of toolCalls) {
+      if (!resultIDs.has(tc.id)) {
+        step.parts.push({ type: "error", message: `Unpaired tool call: ${tc.name} (${tc.id})` })
+      }
+    }
+    return step
+  }
+
+  function allCallsPaired(step: Step): boolean {
+    const calls = step.parts.filter((p): p is ToolCall => p.type === "tool_call")
+    if (calls.length === 0) return false
+    const resultIDs = new Set(
+      step.parts.filter((p): p is ToolResult => p.type === "tool_result").map((r) => r.callID),
+    )
+    return calls.every((tc) => resultIDs.has(tc.id))
+  }
+
+  function closeIfPaired(steps: Step[], step: Step | undefined): Step | undefined {
+    if (step && step.role === "assistant" && allCallsPaired(step)) {
+      steps.push(step)
+      return undefined
+    }
+    return step
+  }
+
+  // ── Claude parser ─────────────────────────────────────────────────
+
+  const CLAUDE_META_TYPES = new Set([
+    "ai-title",
+    "last-prompt",
+    "snapshot",
+    "mode",
+    "attachment",
+  ])
+
+  function parseClaudeSteps(objects: unknown[]): { steps: Step[]; unsupported: number } {
+    const steps: Step[] = []
+    let pending: Step | undefined
+    let unsupported = 0
+    const seenIDs = new Map<string, ToolCall>()
+
+    for (const obj of objects) {
+      if (!isRecord(obj)) throw new ParseError("Expected JSON object")
+
+      const topType = obj.type
+
+      // Skip metadata records
+      if (typeof topType === "string" && CLAUDE_META_TYPES.has(topType)) continue
+
+      if (topType !== "user" && topType !== "assistant") continue
+
+      // Skip sidechain records
+      if (obj.isSidechain === true) continue
+
+      const message = obj.message
+      if (!isRecord(message)) throw new ParseError("Expected message object")
+      const role = message.role
+      if (role !== "user" && role !== "assistant") {
+        throw new ParseError(`Unexpected message role: ${String(role)}`)
+      }
+      const content = typeof message.content === "string"
+        ? [{ type: "text", text: message.content }]
+        : message.content
+      if (!isArray(content)) throw new ParseError(`Expected string or content array for ${role}`)
+
+      if (role === "assistant") {
+        // Merge consecutive assistants into the open step
+        if (pending && pending.role === "assistant") {
+          const { parts, unsupported: u } = parseClaudeBlocks(content, seenIDs)
+          unsupported += u
+          pending.parts.push(...parts)
+        } else {
+          // New assistant — close any previous pending
+          if (pending) {
+            steps.push(markUnpaired(pending))
+            pending = undefined
+          }
+          const { parts, unsupported: u } = parseClaudeBlocks(content, seenIDs)
+          unsupported += u
+          pending = { role: "assistant", parts }
+        }
+      } else {
+        // role === "user"
+        const hasToolResults = content.some(
+          (block) => isRecord(block) && block.type === "tool_result",
+        )
+
+        if (hasToolResults && pending && pending.role === "assistant") {
+          // Pair tool_results with the pending assistant's tool_calls
+          const { results, unsupported: u } = parseClaudeToolResults(content)
+          unsupported += u
+          pending.parts.push(...results)
+
+          // Check if all pending tool calls now have results
+          const pendingCalls = pending.parts.filter((p): p is ToolCall => p.type === "tool_call")
+          const pendingResults = pending.parts.filter((p): p is ToolResult => p.type === "tool_result")
+          const resultIDs = new Set(pendingResults.map((r) => r.callID))
+          const allPaired = pendingCalls.every((tc) => resultIDs.has(tc.id))
+
+          if (allPaired) {
+            // Close the step — result set complete
+            steps.push(pending)
+            pending = undefined
+          }
+          const userBlocks = content.filter(
+            (block) => !isRecord(block) || (block.type !== "tool_result" && block.type !== "server_tool_result"),
+          )
+          if (userBlocks.length > 0) {
+            if (pending) {
+              steps.push(markUnpaired(pending))
+              pending = undefined
+            }
+            const parsed = parseClaudeBlocks(userBlocks, seenIDs)
+            unsupported += parsed.unsupported
+            steps.push({ role: "user", parts: parsed.parts })
+          }
+        } else {
+          // Non-tool-result user → close pending, start new user step
+          if (pending) {
+            steps.push(markUnpaired(pending))
+            pending = undefined
+          }
+          const { parts, unsupported: u } = parseClaudeBlocks(content, seenIDs)
+          unsupported += u
+          steps.push({ role: "user", parts })
+        }
+      }
+    }
+
+    // Emit any remaining pending step
+    if (pending) steps.push(markUnpaired(pending))
+
+    return { steps, unsupported }
+  }
+
+  function parseClaudeBlocks(
+    blocks: unknown[],
+    seenIDs: Map<string, ToolCall>,
+  ): { parts: Part[]; unsupported: number } {
+    const parts: Part[] = []
+    let unsupported = 0
+
+    for (const block of blocks) {
+      if (!isRecord(block)) {
+        unsupported++
+        continue
+      }
+
+      const type = block.type
+      if (type === "text") {
+        parts.push({ type: "text", text: String(block.text ?? "") })
+      } else if (type === "thinking") {
+        parts.push({ type: "reasoning", text: String(block.thinking ?? "") })
+      } else if (type === "tool_use") {
+        const tc: ToolCall = {
+          type: "tool_call",
+          id: String(block.id ?? ""),
+          name: String(block.name ?? ""),
+          input: block.input,
+        }
+        parts.push(tc)
+        seenIDs.set(tc.id, tc)
+      } else if (type === "tool_result") {
+        parts.push({
+          type: "tool_result",
+          callID: String(block.tool_use_id ?? ""),
+          content: extractToolContent(block.content).content,
+          error: block.is_error === true,
+        })
+      } else if (type === "redacted_thinking") {
+        unsupported++
+        parts.push({ type: "unsupported", reason: "encrypted reasoning block" })
+      } else {
+        unsupported++
+        parts.push({ type: "unsupported", reason: `unknown content type: ${String(type)}` })
+      }
+    }
+
+    return { parts, unsupported }
+  }
+
+  function parseClaudeToolResults(
+    blocks: unknown[],
+  ): { results: Part[]; unsupported: number } {
+    const results: Part[] = []
+    let unsupported = 0
+
+    for (const block of blocks) {
+      if (!isRecord(block)) {
+        unsupported++
+        continue
+      }
+
+      if (block.type === "tool_result") {
+        const callID = String(block.tool_use_id ?? "")
+        const parsed = extractToolContent(block.content)
+        unsupported += parsed.unsupported
+        const content = parsed.content
+        results.push({
+          type: "tool_result",
+          callID,
+          content,
+          error: block.is_error === true,
+        })
+      } else if (block.type === "server_tool_result") {
+        unsupported++
+        results.push({
+          type: "unsupported",
+          reason: "server_tool_result block",
+        })
+      } else if (block.type !== "text") {
+        // Non-text, non-result block in user tool-result message → unsupported
+        unsupported++
+      }
+    }
+
+    return { results, unsupported }
+  }
+
+  /** Extract string content from Anthropic tool_result content (string or content block array). */
+  function extractToolContent(content: unknown): { content: string; unsupported: number } {
+    if (typeof content === "string") return { content, unsupported: 0 }
+    if (isArray(content)) {
+      const text = content
+        .filter((item): item is Record<string, unknown> => isRecord(item) && item.type === "text")
+        .map((item) => String(item.text ?? ""))
+      const unsupported = content.filter((item) => !isRecord(item) || item.type !== "text").length
+      return { content: text.join("\n"), unsupported }
+    }
+    if (isRecord(content)) return { content: JSON.stringify(content), unsupported: 0 }
+    return { content: String(content ?? ""), unsupported: 0 }
+  }
+
+  // ── Codex parser ──────────────────────────────────────────────────
+
+  function parseCodexSteps(objects: unknown[]): { steps: Step[]; unsupported: number } {
+    const steps: Step[] = []
+    let pending: Step | undefined
+    let unsupported = 0
+    let seenSessionMeta = false
+
+    for (const obj of objects) {
+      if (!isRecord(obj)) throw new ParseError("Expected JSON object")
+
+      const itemType = obj.type
+
+      if (itemType === "session_meta") {
+        seenSessionMeta = true
+        continue
+      }
+
+      if (itemType === "turn_context" || itemType === "event_msg" || itemType === "world_state") {
+        // Metadata records — skip
+        continue
+      }
+
+      if (itemType !== "response_item") {
+        // Unknown top-level type
+        unsupported++
+        continue
+      }
+
+      const payload = obj.payload
+      if (!isRecord(payload)) {
+        unsupported++
+        continue
+      }
+
+      const riType = payload.type
+
+      if (riType === "message") {
+        const role = payload.role
+
+        if (role === "user") {
+          // Close pending, start new user
+          if (pending) {
+            steps.push(markUnpaired(pending))
+            pending = undefined
+          }
+          const text = extractCodexText(payload.content)
+          steps.push({ role: "user", parts: [{ type: "text", text }] })
+        } else if (role === "assistant") {
+          // Assistant message — close pending if result set is complete
+          const text = extractCodexText(payload.content)
+          if (pending && pending.role === "assistant") {
+            const pendingCalls = pending.parts.filter((p): p is ToolCall => p.type === "tool_call")
+            const pendingResults = pending.parts.filter((p): p is ToolResult => p.type === "tool_result")
+            const resultIDs = new Set(pendingResults.map((r) => r.callID))
+            const allPaired = pendingCalls.length > 0 && pendingCalls.every((tc) => resultIDs.has(tc.id))
+            if (allPaired) {
+              steps.push(pending)
+              pending = text.length > 0 ? { role: "assistant", parts: [{ type: "text", text }] } : undefined
+            } else {
+              // Pending has unpaired calls — merge text into it
+              if (text.length > 0) pending.parts.push({ type: "text", text })
+            }
+          } else {
+            // No pending or non-assistant pending — start new text-only step
+            if (text.length > 0) {
+              pending = { role: "assistant", parts: [{ type: "text", text }] }
+            } else {
+              // Empty assistant content — count as unsupported, skip
+              unsupported++
+            }
+          }
+        }
+      } else if (riType === "function_call" || riType === "custom_tool_call") {
+        // Close fully-paired step before starting a new tool round
+        pending = closeIfPaired(steps, pending)
+
+        const callID = String(payload.call_id ?? "")
+        const name = String(payload.name ?? "")
+        const input = parseCodexToolInput(riType, payload)
+
+        const tc: ToolCall = { type: "tool_call", id: callID, name, input }
+        const status = payload.status
+        if (status === "failed" || status === "error" || status === "incomplete") tc.status = status
+
+        if (pending && pending.role === "assistant") {
+          pending.parts.push(tc)
+        } else {
+          if (pending) {
+            steps.push(markUnpaired(pending))
+            pending = undefined
+          }
+          pending = { role: "assistant", parts: [tc] }
+        }
+      } else if (riType === "function_call_output" || riType === "custom_tool_call_output") {
+        const callID = String(payload.call_id ?? "")
+        const parsed = extractCodexToolOutput(payload.output)
+        unsupported += parsed.unsupported
+        const content = parsed.content
+
+        if (pending && pending.role === "assistant") {
+          const toolCalls = pending.parts.filter((p): p is ToolCall => p.type === "tool_call")
+          const found = toolCalls.some((tc) => tc.id === callID)
+          if (found) {
+            pending.parts.push({ type: "tool_result", callID, content })
+          } else {
+            unsupported++
+          }
+        } else {
+          unsupported++
+        }
+      } else if (riType === "reasoning") {
+        // Close fully-paired step before reasoning in case it starts a new turn
+        pending = closeIfPaired(steps, pending)
+
+        const summary = payload.summary
+        const text = extractCodexReasoningText(summary)
+
+        if (text.length === 0) {
+          // Encrypted-only reasoning
+          unsupported++
+          if (pending && pending.role === "assistant") {
+            pending.parts.push({ type: "unsupported", reason: "encrypted reasoning block" })
+          } else {
+            // Track as unsupported without adding to steps directly
+          }
+        } else {
+          if (pending && pending.role === "assistant") {
+            pending.parts.push({ type: "reasoning", text })
+          } else {
+            if (pending) {
+              steps.push(markUnpaired(pending))
+              pending = undefined
+            }
+            pending = { role: "assistant", parts: [{ type: "reasoning", text }] }
+          }
+        }
+      } else {
+        // Unknown response_item type
+        unsupported++
+      }
+    }
+
+    if (!seenSessionMeta) {
+      throw new ParseError("Missing session_meta record in Codex transcript")
+    }
+
+    // Emit pending step
+    if (pending) steps.push(markUnpaired(pending))
+
+    return { steps, unsupported }
+  }
+
+  function parseCodexToolInput(riType: string, payload: Record<string, unknown>): unknown {
+    if (riType === "function_call") {
+      const args = payload.arguments
+      const str = typeof args === "string" ? args : JSON.stringify(args ?? {})
+      const parsed = safeParse(str)
+      if (isRecord(parsed)) return parsed
+      return { raw: str }
+    }
+    // custom_tool_call — input is already an object
+    const input = payload.input
+    if (isRecord(input)) return input
+    return { raw: JSON.stringify(input ?? {}) }
+  }
+
+  function extractCodexText(content: unknown): string {
+    if (typeof content === "string") return content
+    if (isArray(content)) {
+      return (content as unknown[])
+        .filter((c): c is Record<string, unknown> => isRecord(c))
+        .filter((c) => c.type === "input_text" || c.type === "output_text" || c.type === "text")
+        .map((c) => String(c.text ?? ""))
+        .join("")
+    }
+    return ""
+  }
+
+  function extractCodexToolOutput(output: unknown): { content: string; unsupported: number } {
+    if (typeof output === "string") return { content: output, unsupported: 0 }
+    if (isArray(output)) {
+      const text = output
+        .filter(
+          (item): item is Record<string, unknown> =>
+            isRecord(item) && (item.type === "input_text" || item.type === "output_text" || item.type === "text"),
+        )
+        .map((item) => String(item.text ?? ""))
+      const unsupported = output.filter(
+        (item) =>
+          !isRecord(item) || (item.type !== "input_text" && item.type !== "output_text" && item.type !== "text"),
+      ).length
+      return { content: text.join("\n"), unsupported }
+    }
+    if (isRecord(output)) return { content: JSON.stringify(output), unsupported: 0 }
+    return { content: String(output ?? ""), unsupported: 0 }
+  }
+
+  function extractCodexReasoningText(summary: unknown): string {
+    if (!isArray(summary)) return ""
+    return (summary as unknown[])
+      .filter((c): c is Record<string, unknown> => isRecord(c) && c.type === "summary_text")
+      .map((c) => String((c as Record<string, unknown>).text ?? ""))
+      .join("")
+  }
+
+  // ── Mapping ────────────────────────────────────────────────────────
+
+  const IMPORT_NOTICE = "---\n*This conversation was imported from an external session. Some tool outputs and context may not be fully represented.*"
+
+  export type MappedMessage = {
+    info: Record<string, any>
+    parts: Record<string, any>[]
+  }
+
+  /**
+   * Map a parsed Transcript to ordered message info + part records ready for
+   * session write. Uses ascending IDs in transcript order.
+   */
+  export function mapTranscript(
+    transcript: Transcript,
+    opts: {
+      sessionID: string
+      agent: string
+      providerID: string
+      modelID: string
+      directory: string
+      worktree: string
+      sourceModel?: { providerID: string; modelID: string }
+    },
+  ): { messages: MappedMessage[]; dropped: string[] } {
+    idCounter = 0
+    const msgs: MappedMessage[] = []
+    const dropped: string[] = []
+
+    for (const step of transcript.steps) {
+      if (step.role === "user") {
+        const info = {
+          id: id("message"),
+          sessionID: opts.sessionID,
+          role: "user" as const,
+          time: { created: Date.now() },
+          agent: opts.agent,
+          model: { providerID: opts.providerID, modelID: opts.modelID },
+        }
+        const { parts, dropped: d } = mapUserParts(step.parts, info.id, opts.sessionID)
+        dropped.push(...d)
+        msgs.push({ info, parts })
+      } else {
+        // assistant
+        const parentID = lastUserID(msgs)
+        const src = opts.sourceModel ?? { providerID: opts.providerID, modelID: opts.modelID }
+        const now = Date.now()
+        const info = {
+          id: id("message"),
+          sessionID: opts.sessionID,
+          role: "assistant" as const,
+          parentID,
+          time: { created: now, completed: now },
+          mode: opts.agent,
+          agent: opts.agent,
+          cost: 0,
+          tokens: { input: 0, output: 0, reasoning: 0, cache: { read: 0, write: 0 } },
+          modelID: src.modelID,
+          providerID: src.providerID,
+          path: { cwd: opts.directory, root: opts.worktree },
+          finish: "stop" as const,
+        }
+        const { parts, dropped: d } = mapAssistantParts(step.parts, info.id, opts.sessionID)
+        dropped.push(...d)
+        msgs.push({ info, parts })
+      }
+    }
+
+    // Append the ignored import notice to the final assistant.
+    attachNotice(msgs, transcript.unsupported, dropped, opts)
+
+    return { messages: msgs, dropped }
+  }
+
+  let idCounter = 0
+  function id(prefix: "message" | "part"): string {
+    idCounter++
+    return `__resume_${prefix}_${idCounter}`
+  }
+
+  function lastUserID(msgs: MappedMessage[]): string {
+    for (let i = msgs.length - 1; i >= 0; i--) {
+      const info = msgs[i].info
+      if (info.role === "user" && typeof info.id === "string") return info.id
+    }
+    return ""
+  }
+
+  function mapUserParts(parts: Part[], msgID: string, sesID: string): { parts: Record<string, unknown>[]; dropped: string[] } {
+    const out: Record<string, unknown>[] = []
+    const dropped: string[] = []
+    for (const part of parts) {
+      const base = { id: id("part"), messageID: msgID, sessionID: sesID }
+      if (part.type === "text") {
+        out.push({ ...base, type: "text", text: part.text })
+      } else if (part.type === "tool_result") {
+        out.push({
+          ...base,
+          type: "text",
+          text: `Tool result for ${part.callID}: ${part.content}`,
+          synthetic: true,
+        })
+      } else if (part.type === "unsupported") {
+        dropped.push(part.reason)
+      } else if (part.type === "error") {
+        dropped.push(`error: ${part.message}`)
+      }
+      // reasoning, tool_call in user messages are ignored (should not happen)
+    }
+    return { parts: out, dropped }
+  }
+
+  function mapAssistantParts(parts: Part[], msgID: string, sesID: string): { parts: Record<string, unknown>[]; dropped: string[] } {
+    const now = Date.now()
+    const toolParts = new Map<string, Array<{ part: Record<string, unknown>; index: number; status?: ToolCall["status"] }>>()
+    const results: Part[] = []
+    const out: Record<string, unknown>[] = []
+    const dropped: string[] = []
+    const base = (): { id: string; messageID: string; sessionID: string } => ({
+      id: id("part"),
+      messageID: msgID,
+      sessionID: sesID,
+    })
+
+    // Pass 1: collect tool calls + results, emit non-tool parts
+    for (const part of parts) {
+      if (part.type === "tool_call") {
+        const p = {
+          ...base(),
+          type: "tool",
+          callID: part.id || `tc_${toolParts.size}`,
+          tool: part.name,
+          state: {
+            status: "running" as const,
+            input: isRecord(part.input) ? part.input : { raw: part.input },
+            time: { start: now },
+          },
+        }
+        out.push(p)
+        const entries = toolParts.get(part.id) ?? []
+        entries.push({ part: p, index: out.length - 1, status: part.status })
+        toolParts.set(part.id, entries)
+      } else if (part.type === "tool_result") {
+        results.push(part)
+      } else if (part.type === "text") {
+        out.push({ ...base(), type: "text", text: part.text })
+      } else if (part.type === "reasoning") {
+        out.push({ ...base(), type: "reasoning", text: part.text, time: { start: now } })
+      } else if (part.type === "unsupported") {
+        dropped.push(part.reason)
+      } else if (part.type === "error") {
+        dropped.push(`error: ${part.message}`)
+      }
+    }
+
+    // Pass 2: pair results with tool calls
+    for (const item of results) {
+      const result = item as ToolResult
+        const entry = toolParts.get(result.callID)?.find(
+          (candidate) => (candidate.part.state as Record<string, unknown>).status === "running",
+        )
+      if (entry) {
+        const tp = entry.part
+        if (result.error) {
+          tp.state = {
+            status: "error" as const,
+            input: (tp.state as Record<string, unknown>).input,
+            error: result.content || "Tool call returned an error.",
+            time: { start: now, end: now },
+          }
+        } else {
+          tp.state = {
+            status: "completed" as const,
+            input: (tp.state as Record<string, unknown>).input,
+            output: result.content,
+            title: (tp as Record<string, unknown>).tool as string,
+            metadata: {},
+            time: { start: now, end: now },
+          }
+        }
+        out[entry.index] = tp
+      } else {
+        out.push({ ...base(), type: "text", text: `Tool result: ${result.content}`, synthetic: true })
+      }
+    }
+
+    // Mark any still-running tool calls as error
+    for (const entries of toolParts.values()) {
+      for (const entry of entries) {
+        const tp = entry.part
+        if ((tp.state as Record<string, unknown>).status === "running") {
+          tp.state = {
+            status: "error" as const,
+            input: (tp.state as Record<string, unknown>).input,
+            error: entry.status ?? "No result received for this tool call.",
+            time: { start: now, end: now },
+          }
+          out[entry.index] = tp
+        }
+      }
+    }
+
+    return { parts: out, dropped }
+  }
+
+  function attachNotice(
+    msgs: MappedMessage[],
+    unsupported: number,
+    dropped: string[],
+    opts: {
+      sessionID: string
+      agent: string
+      providerID: string
+      modelID: string
+      directory: string
+      worktree: string
+    },
+  ) {
+    const lines: string[] = [IMPORT_NOTICE]
+    if (unsupported > 0) lines.push(`${unsupported} unsupported item(s) were skipped during import.`)
+    if (dropped.length > 0) {
+      const unique = [...new Set(dropped)]
+      lines.push(`Dropped unsupported content: ${unique.join(", ")}.`)
+    }
+    const text = lines.join("\n\n")
+
+    const last = msgs.at(-1)
+    if (last?.info.role === "assistant") {
+      // Append notice to the last assistant
+      last.parts.push({
+        id: id("part"),
+        messageID: last.info.id as string,
+        sessionID: opts.sessionID,
+        type: "text",
+        text,
+        synthetic: true,
+        ignored: true,
+      })
+      return
+    }
+
+    // No assistant yet — create a complete notice-only assistant after the last user
+    const parent = lastUserID(msgs)
+    const info = {
+      id: id("message"),
+      sessionID: opts.sessionID,
+      role: "assistant" as const,
+      parentID: parent,
+      time: { created: Date.now(), completed: Date.now() },
+      mode: opts.agent,
+      agent: opts.agent,
+      cost: 0,
+      tokens: { input: 0, output: 0, reasoning: 0, cache: { read: 0, write: 0 } },
+      modelID: opts.modelID,
+      providerID: opts.providerID,
+      path: { cwd: opts.directory, root: opts.worktree },
+      finish: "stop" as const,
+    }
+    const parts = [
+      {
+        id: id("part"),
+        messageID: info.id,
+        sessionID: opts.sessionID,
+        type: "text" as const,
+        text,
+        synthetic: true,
+        ignored: true,
+      },
+    ]
+    msgs.push({ info, parts })
+  }
+
+  // ── Command definitions ────────────────────────────────────────────
+
+  export const resumeClaude = {
+    name: "resume-claude",
+    description: "import a Claude Code session transcript",
+    source: "command" as const,
+    template: "",
+    hints: ["$ARGUMENTS"],
+  }
+
+  export const resumeCodex = {
+    name: "resume-codex",
+    description: "import an OpenAI Codex session transcript",
+    source: "command" as const,
+    template: "",
+    hints: ["$ARGUMENTS"],
+  }
+}
diff --git a/packages/opencode/src/kilocode/tool/grep-signal-controls.ts b/packages/opencode/src/kilocode/tool/grep-signal-controls.ts
deleted file mode 100644
index 49eb582c645..00000000000
--- a/packages/opencode/src/kilocode/tool/grep-signal-controls.ts
+++ /dev/null
@@ -1,64 +0,0 @@
-import { NonNegativeInt, PositiveInt } from "@opencode-ai/core/schema"
-import { Schema } from "effect"
-
-export const DEFAULT_LIMIT = 100
-
-export const fields = {
-  context: Schema.optional(NonNegativeInt).annotate({
-    description: "Number of context lines to show before and after each match (default 0)",
-  }),
-  limit: Schema.optional(PositiveInt).annotate({
-    description: "Maximum matching lines to return (default 100)",
-  }),
-  literal: Schema.optional(Schema.Boolean).annotate({
-    description: "Treat pattern as plain text instead of a regex (default false)",
-  }),
-  ignoreCase: Schema.optional(Schema.Boolean).annotate({
-    description: "Match without regard to letter case (default false)",
-  }),
-}
-
-type Input = {
-  readonly context?: number
-  readonly limit?: number
-  readonly literal?: boolean
-  readonly ignoreCase?: boolean
-}
-
-export const metadata = (input: Input, limit: number, context: number) => ({
-  context,
-  limit,
-  literal: input.literal,
-  ignoreCase: input.ignoreCase,
-})
-
-export const options = (input: Input, limit: number, context: number) => ({
-  limit,
-  context,
-  literal: input.literal,
-  ignoreCase: input.ignoreCase,
-})
-
-export const describe = (description: string) => `${description}
-- Searches file contents using regular expressions by default; use literal=true for plain-text patterns
-- Use ignoreCase=true for case-insensitive matching, context=N for surrounding lines, and limit=N to bound matches (default 100)
-- Context lines are explicitly labeled when requested`
-
-export const line = (
-  row: { readonly line: number; readonly text: string; readonly context: boolean },
-  context: number,
-) => {
-  const label = context === 0 ? `Line ${row.line}` : `${row.context ? "[context]" : "[match]"} Line ${row.line}`
-  return `  ${label}: ${row.text}`
-}
-
-export const limitNotice = (limit: number) =>
-  `${limit} matches limit reached. Use limit=${Math.min(Number.MAX_SAFE_INTEGER, limit * 2)} for more, or refine pattern.`
-
-export const notices = (rows: readonly { readonly textTruncated: boolean }[]) => {
-  const output: string[] = []
-  if (rows.some((row) => row.textTruncated)) {
-    output.push("", "Some matching or context lines were truncated. Use read for full lines.")
-  }
-  return output
-}
diff --git a/packages/opencode/src/kilocode/tool/tool.ts b/packages/opencode/src/kilocode/tool/tool.ts
new file mode 100644
index 00000000000..f0b89c2ea90
--- /dev/null
+++ b/packages/opencode/src/kilocode/tool/tool.ts
@@ -0,0 +1,55 @@
+import { Schema, SchemaIssue } from "effect"
+
+const formatter = SchemaIssue.makeFormatterStandardSchemaV1()
+const count = 20
+const limit = 4 * 1024
+
+export function format(error: unknown) {
+  if (!Schema.isSchemaError(error)) {
+    return String(error)
+  }
+  const result = formatter(error.issue)
+  if (result.issues.length === 0) {
+    return "The input did not match the expected schema. Please rewrite the arguments so they satisfy it."
+  }
+  const issues = result.issues.slice(0, count)
+  const lines: string[] = []
+  for (const issue of issues) {
+    const line = `${path(issue.path)}: ${reason(issue.message)}`
+    const more = result.issues.length - lines.length - 1
+    const suffix = more > 0 ? `\n…and ${more} more` : ""
+    if ([...lines, line].join("\n").length + suffix.length > limit) {
+      break
+    }
+    lines.push(line)
+  }
+  const more = result.issues.length - lines.length
+  const suffix = more > 0 ? `\n…and ${more} more` : ""
+  if (lines.length > 0) {
+    return `${lines.join("\n")}${suffix}`
+  }
+  const line = `${path(issues[0].path)}: ${reason(issues[0].message)}`
+  const rest = result.issues.length - 1
+  const tail = rest > 0 ? `\n…and ${rest} more` : ""
+  return `${line.slice(0, limit - tail.length - 1)}…${tail}`
+}
+
+function path(keys: ReadonlyArray<unknown> | undefined) {
+  const value = (keys ?? [])
+    .map((key) => {
+      const segment = typeof key === "object" && key !== null && "key" in key ? key.key : key
+      return typeof segment === "number" ? `[${segment}]` : `[${JSON.stringify(String(segment))}]`
+    })
+    .join("")
+  return value || "input"
+}
+
+function reason(message: string) {
+  if (message.toLowerCase().includes("required")) {
+    return message
+  }
+  if (/\bmissing\b/i.test(message)) {
+    return "is missing and is required"
+  }
+  return message
+}
diff --git a/packages/opencode/src/session/prompt.ts b/packages/opencode/src/session/prompt.ts
index 1928ef8625b..20626cbd1fa 100644
--- a/packages/opencode/src/session/prompt.ts
+++ b/packages/opencode/src/session/prompt.ts
@@ -1,6 +1,7 @@
 import { LayerNode } from "@opencode-ai/core/effect/layer-node"
 import { PermissionV1 } from "@opencode-ai/core/v1/permission"
 import path from "path"
+import fs from "node:fs" // kilocode_change
 import { SessionV1 } from "@opencode-ai/core/v1/session"
 import os from "os"
 import { KiloSessionPrompt } from "@/kilocode/session/prompt" // kilocode_change
@@ -87,6 +88,7 @@ import { SessionReminders } from "./reminders"
 import { SessionTools } from "./tools"
 import { LLMEvent } from "@opencode-ai/llm"
 import { RepositoryCache } from "@opencode-ai/core/repository-cache" // kilocode_change
+import { SessionResume } from "@/kilocode/session-resume" // kilocode_change
 
 // @ts-ignore
 globalThis.AI_SDK_LOG_WARNINGS = false
@@ -124,10 +126,10 @@ export interface Interface {
   // kilocode_change end
   readonly loop: (input: LoopInput) => Effect.Effect<SessionV1.WithParts>
   readonly shell: (input: ShellInput) => Effect.Effect<SessionV1.WithParts, Session.BusyError>
-  // kilocode_change start - commands can fail on unmet agent requirements
+  // kilocode_change start - commands can fail on unmet agent requirements or resume errors
   readonly command: (
     input: CommandInput,
-  ) => Effect.Effect<SessionV1.WithParts, Image.Error | Agent.RequirementBlockedError>
+  ) => Effect.Effect<SessionV1.WithParts, Image.Error | Agent.RequirementBlockedError | Error>
   // kilocode_change end
   readonly resolvePromptParts: (template: string) => Effect.Effect<PromptInput["parts"]>
 }
@@ -1962,6 +1964,293 @@ export const layer = Layer.effect(
       )
     })
 
+    // kilocode_change start - resume command handler
+    const isResumeCommand = (name: string): SessionResume.Format | undefined => {
+      if (name === "resume-claude") return "claude"
+      if (name === "resume-codex") return "codex"
+      return undefined
+    }
+
+    const handleResume = Effect.fn("SessionPrompt.handleResume")(function* (input: {
+      cmdInput: CommandInput
+      format: SessionResume.Format
+    }) {
+      const ctx = yield* InstanceState.context
+      const session = yield* sessions.get(input.cmdInput.sessionID).pipe(Effect.orDie)
+      // kilocode_change start - test-only resume roots via Context.Service
+      const opt = yield* Effect.serviceOption(SessionResume.ResumeRoots)
+      const roots = Option.getOrUndefined(opt) ?? {}
+      // kilocode_change end
+
+      // Reject nonempty sessions
+      const msgs = yield* sessions.messages({ sessionID: input.cmdInput.sessionID }).pipe(Effect.orDie)
+      if (msgs.length > 0) {
+        const error = new NamedError.Unknown({
+          message: "Start a new Kilo session, then run the resume command again.",
+        })
+        yield* events.publish(Session.Event.Error, { sessionID: input.cmdInput.sessionID, error: error.toObject() })
+        return yield* Effect.fail(error)
+      }
+
+      // Resolve agent
+      const agentName = input.cmdInput.agent
+      const agent = agentName ? yield* agents.get(agentName) : yield* agents.defaultInfo()
+      if (!agent) {
+        const available = (yield* agents.list()).filter((a) => !a.hidden).map((a) => a.name)
+        const hint = available.length ? ` Available agents: ${available.join(", ")}` : ""
+        const error = new NamedError.Unknown({ message: `Agent not found: "${agentName}".${hint}` })
+        yield* events.publish(Session.Event.Error, { sessionID: input.cmdInput.sessionID, error: error.toObject() })
+        return yield* Effect.fail(error)
+      }
+      yield* agents.guardRequirements(agent)
+
+      // Resolve model
+      const model = yield* Effect.gen(function* () {
+        if (input.cmdInput.model) return Provider.parseModel(input.cmdInput.model)
+        if (agent.model) return agent.model
+        return yield* currentModel(input.cmdInput.sessionID)
+      })
+      yield* getModel(model.providerID, model.modelID, input.cmdInput.sessionID)
+
+      const trimmed = input.cmdInput.arguments.trim()
+      let uuid: string
+
+      if (trimmed.length === 0) {
+        // Show question picker: discover sessions of the requested format only
+        const cwd = ctx.directory
+        let claudeFiles: string[] = []
+        if (input.format === "claude") {
+          try {
+            claudeFiles = SessionResume.discoverClaude({ cwd, ...roots })
+          } catch (cause) {
+            const code = typeof cause === "object" && cause !== null && "code" in cause ? cause.code : undefined
+            if (code !== "ENOENT") {
+              const error = new NamedError.Unknown({ message: "Unreadable Claude transcript directory" })
+              yield* events.publish(Session.Event.Error, { sessionID: input.cmdInput.sessionID, error: error.toObject() })
+              return yield* Effect.fail(error)
+            }
+          }
+        }
+        const codexExit = input.format === "codex"
+          ? yield* Effect.exit(Effect.promise(() => SessionResume.discoverCodex({ cwd, ...roots })))
+          : undefined
+        const codexFiles = (codexExit && Exit.isSuccess(codexExit)) ? codexExit.value : []
+
+        type Entry = { id: string; format: SessionResume.Format; mtime?: number }
+        const entries: Entry[] = []
+        for (const f of claudeFiles) {
+          const id = path.basename(f, ".jsonl")
+          let mtime: number | undefined
+          try { mtime = fs.statSync(f).mtimeMs } catch { mtime = undefined }
+          entries.push({ id, format: "claude", mtime })
+        }
+        for (const f of codexFiles) {
+          const base = path.basename(f, ".jsonl")
+          // Derive UUID from final -<uuid> segment: rollout-YYYY-MM-DDTHH-MM-SS-<uuid>
+          const raw = base.slice("rollout-".length)
+          const id = raw.split("-").slice(-5).join("-")
+          let mtime: number | undefined
+          try { mtime = fs.statSync(f).mtimeMs } catch { mtime = undefined }
+          entries.push({ id, format: "codex", mtime })
+        }
+
+        if (entries.length === 0) {
+          const error = new NamedError.Unknown({
+            message: "No session transcripts found in the current directory. Use /resume-claude <uuid> or /resume-codex <uuid> with an explicit UUID.",
+          })
+          yield* events.publish(Session.Event.Error, { sessionID: input.cmdInput.sessionID, error: error.toObject() })
+          return yield* Effect.fail(error)
+        }
+
+        // Limit and format labels: UUID only, ISO mtime as description
+        const display = entries.slice(0, 10)
+        const options = display.map((e) => {
+          const timeLabel = e.mtime ? new Date(e.mtime).toISOString() : "unknown time"
+          return {
+            label: e.id,
+            description: timeLabel,
+          }
+        })
+
+        const answers = yield* question.ask({
+          sessionID: input.cmdInput.sessionID,
+          questions: [
+            {
+              question: `Which recent ${input.format === "claude" ? "Claude Code" : "Codex"} session do you want to resume?`,
+              header: "Resume session",
+              options,
+              multiple: false,
+              custom: false,
+            },
+          ],
+          blocking: true,
+        })
+        const pickerAnswer = answers[0]?.[0]
+        if (pickerAnswer === undefined || pickerAnswer === "") {
+          return yield* Effect.fail(new NamedError.Unknown({ message: "No session selected." }))
+        }
+        const pickerIdx = options.findIndex((o) => o.label === pickerAnswer)
+        if (pickerIdx < 0 || pickerIdx >= display.length) {
+          const error = new NamedError.Unknown({
+            message: `Invalid selection: "${pickerAnswer}"`,
+          })
+          yield* events.publish(Session.Event.Error, { sessionID: input.cmdInput.sessionID, error: error.toObject() })
+          return yield* Effect.fail(error)
+        }
+        uuid = display[pickerIdx].id
+      } else {
+        uuid = trimmed
+      }
+
+      // Validate UUID
+      if (!SessionResume.isUUID(uuid)) {
+        const error = new NamedError.Unknown({
+          message: `Invalid UUID: ${uuid}`,
+        })
+        yield* events.publish(Session.Event.Error, { sessionID: input.cmdInput.sessionID, error: error.toObject() })
+        return yield* Effect.fail(error)
+      }
+
+      // Discover and parse
+      const cwd = ctx.directory
+      const codexExit = input.format === "codex"
+        ? yield* Effect.exit(Effect.promise(() => SessionResume.discoverCodex({ cwd, id: uuid, ...roots })))
+        : undefined
+      let file: string | undefined
+      if (input.format === "claude") {
+        try {
+          file = SessionResume.discoverClaude({ cwd, id: uuid, ...roots })[0]
+        } catch (cause) {
+          if (cause instanceof SessionResume.ParseError) {
+            const error = new NamedError.Unknown({ message: cause.message })
+            yield* events.publish(Session.Event.Error, { sessionID: input.cmdInput.sessionID, error: error.toObject() })
+            return yield* Effect.fail(error)
+          }
+          const code = typeof cause === "object" && cause !== null && "code" in cause ? cause.code : undefined
+          if (code !== "ENOENT") {
+            const error = new NamedError.Unknown({ message: `Unreadable Claude transcript: ${uuid}` })
+            yield* events.publish(Session.Event.Error, { sessionID: input.cmdInput.sessionID, error: error.toObject() })
+            return yield* Effect.fail(error)
+          }
+        }
+      } else {
+        file = codexExit && Exit.isSuccess(codexExit) ? codexExit.value[0] : undefined
+      }
+
+      if (!file) {
+        const error = new NamedError.Unknown({
+          message: `No ${input.format === "claude" ? "Claude Code" : "OpenAI Codex"} session found with UUID: ${uuid}`,
+        })
+        yield* events.publish(Session.Event.Error, { sessionID: input.cmdInput.sessionID, error: error.toObject() })
+        return yield* Effect.fail(error)
+      }
+
+      const parseExit = yield* Effect.exit(
+        Effect.tryPromise({
+          try: () => SessionResume.parse(file),
+          catch: (err) => {
+            const msg = err instanceof Error ? err.message : String(err)
+            return new NamedError.Unknown({ message: `Failed to parse session transcript: ${msg}` })
+          },
+        }),
+      )
+
+      if (Exit.isFailure(parseExit)) {
+        const err = Cause.squash(parseExit.cause)
+        if (err instanceof NamedError.Unknown) {
+          yield* events.publish(Session.Event.Error, { sessionID: input.cmdInput.sessionID, error: err.toObject() })
+        }
+        return yield* Effect.failCause(parseExit.cause)
+      }
+
+      const transcript = parseExit.value
+
+      // Reject transcripts without a real user
+      const hasRealUser = transcript.steps.some(
+        (s) => s.role === "user" && s.parts.some((p) => p.type === "text" && p.text.trim().length > 0),
+      )
+      if (!hasRealUser) {
+        const error = new NamedError.Unknown({
+          message: "The transcript contains no user messages. Nothing was imported.",
+        })
+        yield* events.publish(Session.Event.Error, { sessionID: input.cmdInput.sessionID, error: error.toObject() })
+        return yield* Effect.fail(error)
+      }
+
+      // Map transcript to messages
+      const { messages: mapped } = SessionResume.mapTranscript(transcript, {
+        sessionID: input.cmdInput.sessionID,
+        agent: agent.name,
+        providerID: model.providerID,
+        modelID: model.modelID,
+        directory: ctx.directory,
+        worktree: ctx.worktree,
+        sourceModel: transcript.sourceModel,
+      })
+
+      // Reject every assistant before a real user parent before any write
+      if (mapped.length > 0 && mapped[0].info.role !== "user") {
+        const error = new NamedError.Unknown({
+          message: "Transcript starts with an assistant message. The first message must be from a user.",
+        })
+        yield* events.publish(Session.Event.Error, { sessionID: input.cmdInput.sessionID, error: error.toObject() })
+        return yield* Effect.fail(error)
+      }
+
+      // Write messages and parts in order with ascending IDs
+      const idMap = new Map<string, string>()
+
+      for (const item of mapped) {
+        const newID = MessageID.ascending()
+        idMap.set(item.info.id as string, newID)
+
+        const parentID = item.info.role === "assistant"
+          ? (typeof item.info.parentID === "string" ? idMap.get(item.info.parentID) : undefined)
+          : undefined
+
+        const info = {
+          ...item.info,
+          id: newID,
+          sessionID: input.cmdInput.sessionID,
+          ...(parentID && { parentID }),
+        } as SessionV1.Info
+
+        yield* sessions.updateMessage(info)
+
+        for (const part of item.parts) {
+          const partID = PartID.ascending()
+          const p = {
+            ...part,
+            id: partID,
+            messageID: newID,
+            sessionID: input.cmdInput.sessionID,
+          } as SessionV1.Part
+          yield* sessions.updatePart(p)
+        }
+      }
+
+      yield* sessions.touch(input.cmdInput.sessionID)
+
+      // Build result from the final assistant
+      const resultMsgs = yield* sessions.messages({ sessionID: input.cmdInput.sessionID }).pipe(Effect.orDie)
+      const last = resultMsgs.findLast((m) => m.info.role === "assistant")
+      if (!last) {
+        const error = new NamedError.Unknown({ message: "No assistant message found after resume import" })
+        yield* events.publish(Session.Event.Error, { sessionID: input.cmdInput.sessionID, error: error.toObject() })
+        return yield* Effect.fail(error)
+      }
+
+      yield* events.publish(Command.Event.Executed, {
+        name: input.cmdInput.command,
+        sessionID: input.cmdInput.sessionID,
+        arguments: input.cmdInput.arguments,
+        messageID: last.info.id,
+      })
+
+      return last
+    })
+    // kilocode_change end
+
     const command = Effect.fn("SessionPrompt.command")(function* (input: CommandInput) {
       yield* Effect.logInfo("command", {
         "session.id": input.sessionID,
@@ -1979,6 +2268,12 @@ export const layer = Layer.effect(
         throw error
       }
       const agentName = cmd.agent ?? input.agent
+      // kilocode_change start - resume commands import external transcripts
+      const fmt = isResumeCommand(input.command)
+      if (fmt) {
+        return yield* handleResume({ cmdInput: input, format: fmt })
+      }
+      // kilocode_change end
       // kilocode_change start - deprecated review aliases should display a static notice without an LLM turn
       const legacy = legacyReviewMessage(input.command)
       if (legacy) {
diff --git a/packages/opencode/src/tool/grep.ts b/packages/opencode/src/tool/grep.ts
index f4277831685..30a1779208c 100644
--- a/packages/opencode/src/tool/grep.ts
+++ b/packages/opencode/src/tool/grep.ts
@@ -3,20 +3,18 @@ import { Effect, Schema } from "effect"
 import { InstanceState } from "@/effect/instance-state"
 import { FSUtil } from "@opencode-ai/core/fs-util"
 import { Ripgrep } from "@opencode-ai/core/ripgrep"
-import * as KiloGrep from "@/kilocode/tool/grep-signal-controls" // kilocode_change
 import { assertExternalDirectoryEffect } from "./external-directory"
 import DESCRIPTION from "./grep.txt"
 import * as Tool from "./tool"
 
 export const Parameters = Schema.Struct({
-  pattern: Schema.String.annotate({ description: "Pattern to search for in file contents (regex by default)" }), // kilocode_change
+  pattern: Schema.String.annotate({ description: "The regex pattern to search for in file contents" }),
   path: Schema.optional(Schema.String).annotate({
     description: "The directory to search in. Defaults to the current working directory.",
   }),
   include: Schema.optional(Schema.String).annotate({
     description: 'File pattern to include in the search (e.g. "*.js", "*.{ts,tsx}")',
   }),
-  ...KiloGrep.fields, // kilocode_change
 })
 
 export const GrepTool = Tool.define(
@@ -25,12 +23,10 @@ export const GrepTool = Tool.define(
     const fs = yield* FSUtil.Service
     const ripgrep = yield* Ripgrep.Service
     return {
-      description: KiloGrep.describe(DESCRIPTION), // kilocode_change
+      description: DESCRIPTION,
       parameters: Parameters,
-      execute: (params: Schema.Schema.Type<typeof Parameters>, ctx: Tool.Context) =>
+      execute: (params: { pattern: string; path?: string; include?: string }, ctx: Tool.Context) =>
         Effect.gen(function* () {
-          const limit = params.limit ?? KiloGrep.DEFAULT_LIMIT // kilocode_change
-          const context = params.context ?? 0 // kilocode_change
           const empty = {
             title: params.pattern,
             metadata: { matches: 0, truncated: false },
@@ -48,7 +44,6 @@ export const GrepTool = Tool.define(
               pattern: params.pattern,
               path: params.path,
               include: params.include,
-              ...KiloGrep.metadata(params, limit, context), // kilocode_change
             },
           })
 
@@ -71,7 +66,7 @@ export const GrepTool = Tool.define(
             file: info?.type === "File" ? path.basename(search) : undefined, // kilocode_change - constrain exact-file searches
             pattern: params.pattern,
             include: params.include,
-            ...KiloGrep.options(params, limit, context), // kilocode_change
+            limit: 100,
             signal: ctx.abort, // kilocode_change - stop ripgrep when the tool call is cancelled
           })
           // kilocode_change start
@@ -79,20 +74,18 @@ export const GrepTool = Tool.define(
           if (matches.length === 0) return empty
           // kilocode_change end
 
-          const rows = matches.map((item) => ({
-            // kilocode_change
+          const rows = matches.map((item) => ({ // kilocode_change
             path: path.resolve(cwd, item.entry.path),
             line: item.line,
             text: item.text,
-            context: item.context, // kilocode_change
-            textTruncated: item.textTruncated, // kilocode_change
           }))
 
+          const limit = 100
           const truncated = result.truncated // kilocode_change
           const final = rows
           if (final.length === 0) return empty
 
-          const total = rows.filter((row) => !row.context).length // kilocode_change
+          const total = rows.length
           const hasMore = truncated // kilocode_change
           const output = [`Found ${total} matches${hasMore ? " (more matches available)" : ""}`]
 
@@ -103,14 +96,13 @@ export const GrepTool = Tool.define(
               current = match.path
               output.push(`${match.path}:`)
             }
-            output.push(KiloGrep.line(match, context)) // kilocode_change
+            output.push(`  Line ${match.line}: ${match.text}`)
           }
 
           if (truncated) {
             output.push("")
-            output.push(KiloGrep.limitNotice(limit)) // kilocode_change
+            output.push("(Results truncated. Consider using a more specific path or pattern.)")
           }
-          output.push(...KiloGrep.notices(rows)) // kilocode_change
           if (result.partial) output.push("", "(Some paths were inaccessible.)") // kilocode_change
 
           return {
diff --git a/packages/opencode/src/tool/tool.ts b/packages/opencode/src/tool/tool.ts
index e5e7802858c..079627144c8 100644
--- a/packages/opencode/src/tool/tool.ts
+++ b/packages/opencode/src/tool/tool.ts
@@ -7,6 +7,7 @@ import type { Permission } from "../permission"
 import type { SessionID, MessageID } from "../session/schema"
 import * as Truncate from "./truncate"
 import { Agent } from "@/agent/agent"
+import { format } from "@/kilocode/tool/tool" // kilocode_change
 
 interface Metadata {
   [key: string]: any
@@ -118,15 +119,20 @@ function wrap<Parameters extends Schema.Decoder<unknown>, Result extends Metadat
           ...(ctx.callID ? { "tool.call_id": ctx.callID } : {}),
         }
         return Effect.gen(function* () {
-          const decoded = yield* decode(args).pipe(
+          // kilocode_change start
+          const decoded = yield* decode(
+            args,
+            { errors: "all" },
+          ).pipe(
             Effect.mapError(
               (error) =>
                 new InvalidArgumentsError({
                   tool: id,
-                  detail: toolInfo.formatValidationError ? toolInfo.formatValidationError(error) : String(error),
+                  detail: toolInfo.formatValidationError ? toolInfo.formatValidationError(error) : format(error),
                 }),
             ),
           )
+          // kilocode_change end
           const result = yield* execute(decoded as Schema.Schema.Type<Parameters>, ctx)
           if (result.metadata.truncated !== undefined) {
             return result
diff --git a/packages/opencode/test/kilocode/cli-shutdown.test.ts b/packages/opencode/test/kilocode/cli-shutdown.test.ts
index 5a4babfbe09..451124d1547 100644
--- a/packages/opencode/test/kilocode/cli-shutdown.test.ts
+++ b/packages/opencode/test/kilocode/cli-shutdown.test.ts
@@ -19,7 +19,9 @@ mock.module("@opencode-ai/core/installation/version", () => ({
 
 mock.module("@kilocode/kilo-telemetry", () => ({
   Telemetry: {
-    async init() {},
+    async init() {
+      calls.push("telemetry:init")
+    },
     async updateIdentity() {},
     trackCliStart() {},
     trackCliExit(code?: number) {
@@ -36,16 +38,36 @@ mock.module("@kilocode/kilo-telemetry", () => ({
 mock.module("@kilocode/kilo-gateway", () => ({
   ENV_FEATURE: "KILO_FEATURE",
   ENV_VERSION: "KILO_VERSION",
-  async migrateLegacyKiloAuth() {},
+  async migrateLegacyKiloAuth() {
+    calls.push("auth:migrate")
+  },
 }))
 
 mock.module("@/effect/app-runtime", () => ({
   AppRuntime: {
-    async runPromise() {},
+    async runPromise() {
+      calls.push("runtime")
+    },
     async dispose() {},
   },
 }))
 
+mock.module("@/kilocode/log", () => ({
+  KiloLog: {
+    async init() {
+      calls.push("log")
+    },
+  },
+}))
+
+mock.module("@/kilocode/storage/json-migration", () => ({
+  JsonMigration: {
+    async bootstrap() {
+      calls.push("migration")
+    },
+  },
+}))
+
 mock.module("@/config/config", () => ({
   Config: { Service: { use: () => ({ experimental: {} }) } },
 }))
@@ -183,4 +205,17 @@ describe("KiloCli.shutdown", () => {
     expect(calls).toEqual(["track:1", "session", "telemetry", "drain", "dispose"])
     expect(process.exitCode).toBe(1)
   })
+
+  test("skips lifecycle work for parsed informational flags", async () => {
+    const { KiloCli } = await import("../../src/kilocode/cli/setup")
+    await installDrain()
+
+    for (const flag of ["help", "version"] as const) {
+      await KiloCli.bootstrap({ [flag]: true })
+      await KiloCli.shutdown()
+    }
+
+    expect(calls).toEqual([])
+    expect(timeouts).toEqual([])
+  })
 })
diff --git a/packages/opencode/test/kilocode/config-resilience.test.ts b/packages/opencode/test/kilocode/config-resilience.test.ts
index 12949e44cff..7cfd6f3f8e2 100644
--- a/packages/opencode/test/kilocode/config-resilience.test.ts
+++ b/packages/opencode/test/kilocode/config-resilience.test.ts
@@ -6,6 +6,7 @@ import { AppRuntime } from "../../src/effect/app-runtime"
 import { provideTestInstance } from "../fixture/fixture"
 import { Filesystem } from "../../src/util/filesystem"
 import { disposeAllInstances, tmpdir } from "../fixture/fixture"
+import { Flag } from "@opencode-ai/core/flag/flag"
 
 const load = () => AppRuntime.runPromise(Config.Service.use((svc) => svc.get()))
 const warnings = () => AppRuntime.runPromise(Config.Service.use((svc) => svc.warnings()))
@@ -106,6 +107,79 @@ describe("config resilience", () => {
     })
   })
 
+  test.serial(
+    "loads external directory symlinks explicitly allowed by global config without trusting tokens",
+    async () => {
+      const name = "KILO_EXTERNAL_MARKDOWN_SECRET"
+      const env = process.env[name]
+      const config = Flag.KILO_CONFIG
+      process.env[name] = "environment secret"
+      await using tmp = await tmpdir({
+        init: async (dir) => {
+          const project = path.join(dir, "project")
+          const shared = path.join(dir, "shared")
+          const agents = path.join(shared, "agents")
+          const commands = path.join(shared, "commands")
+          const secret = path.join(dir, "secret.txt")
+          const escaped = path.join(dir, "escaped.md")
+          const global = path.join(dir, "global.json")
+          await Filesystem.write(path.join(agents, "shared.md"), "Shared agent prompt")
+          await Filesystem.write(path.join(commands, "shared.md"), "Shared command template")
+          await Filesystem.write(path.join(agents, "env.md"), `{env:${name}}`)
+          await Filesystem.write(path.join(commands, "file.md"), `{file:${secret}}`)
+          await Filesystem.write(secret, "file secret")
+          await Filesystem.write(escaped, "Escaped agent prompt")
+          await fs.symlink(escaped, path.join(agents, "escaped.md"))
+          await fs.mkdir(path.join(project, ".kilo"), { recursive: true })
+          const type = process.platform === "win32" ? "junction" : "dir"
+          await fs.symlink(agents, path.join(project, ".kilo", "agents"), type)
+          await fs.symlink(commands, path.join(project, ".kilo", "commands"), type)
+          await Filesystem.write(
+            global,
+            JSON.stringify({
+              permission: {
+                markdown_source: {
+                  [path.join(agents, "*")]: "allow",
+                  [path.join(commands, "*")]: "allow",
+                },
+              },
+            }),
+          )
+          return { project, global }
+        },
+      })
+      Flag.KILO_CONFIG = tmp.extra.global
+
+      try {
+        await provideTestInstance({
+          directory: tmp.extra.project,
+          fn: async () => {
+            const cfg = await load()
+            const warns = await warnings()
+
+            expect(cfg.agent?.shared).toMatchObject({ prompt: "Shared agent prompt" })
+            expect(cfg.command?.shared).toMatchObject({ template: "Shared command template" })
+            expect(cfg.agent?.env).toBeUndefined()
+            expect(cfg.agent?.escaped).toBeUndefined()
+            expect(cfg.command?.file).toBeUndefined()
+            expect(
+              warns.filter(
+                (warning) =>
+                  warning.path.endsWith("env.md") ||
+                  warning.path.endsWith("escaped.md") ||
+                  warning.path.endsWith("file.md"),
+              ),
+            ).toHaveLength(3)
+          },
+        })
+      } finally {
+        Flag.KILO_CONFIG = config
+        if (env === undefined) delete process.env[name]
+        else process.env[name] = env
+      }
+    },
+  )
+
   test("skips invalid agent markdown configs", async () => {
     await using tmp = await tmpdir({
       init: async (dir) => {
diff --git a/packages/opencode/test/kilocode/config/external-markdown.test.ts b/packages/opencode/test/kilocode/config/external-markdown.test.ts
new file mode 100644
index 00000000000..3263f5b3191
--- /dev/null
+++ b/packages/opencode/test/kilocode/config/external-markdown.test.ts
@@ -0,0 +1,50 @@
+import { describe, expect, test } from "bun:test"
+import fs from "node:fs/promises"
+import path from "node:path"
+import { ExternalMarkdown } from "../../../src/kilocode/config/external-markdown"
+import { tmpdir } from "../../fixture/fixture"
+
+describe("external Markdown sources", () => {
+  test("requires a global allow for the exact canonical directory", async () => {
+    await using tmp = await tmpdir({
+      init: async (dir) => {
+        const source = path.join(dir, "project", ".kilo", "agents")
+        const root = path.join(dir, "shared", "agents")
+        await Bun.write(path.join(root, "shared.md"), "prompt")
+        await fs.mkdir(path.dirname(source), { recursive: true })
+        await fs.symlink(root, source, process.platform === "win32" ? "junction" : "dir")
+        return { dir: path.dirname(source), root }
+      },
+    })
+    const exact = path.join(tmp.extra.root, "*")
+    const input = {
+      dir: tmp.extra.dir,
+      names: ["agents"],
+      permission: { markdown_source: { [exact]: "allow" as const } },
+      origins: { markdown_source: { [exact]: "global" as const } },
+    }
+
+    expect(ExternalMarkdown.scopes(input)).toEqual([
+      { root: tmp.extra.root, source: path.join(tmp.extra.dir, "agents") },
+    ])
+    expect(ExternalMarkdown.scopes({ ...input, origins: { markdown_source: { [exact]: "local" } } })).toEqual([])
+
+    const parent = path.join(path.dirname(tmp.extra.root), "*")
+    expect(
+      ExternalMarkdown.scopes({
+        ...input,
+        permission: { markdown_source: { [parent]: "allow" } },
+        origins: { markdown_source: { [parent]: "global" } },
+      }),
+    ).toEqual([])
+
+    const prefix = `${tmp.extra.root}*`
+    expect(
+      ExternalMarkdown.scopes({
+        ...input,
+        permission: { markdown_source: { [prefix]: "allow" } },
+        origins: { markdown_source: { [prefix]: "global" } },
+      }),
+    ).toEqual([])
+  })
+})
diff --git a/packages/opencode/test/kilocode/fixture/session-resume/claude.jsonl b/packages/opencode/test/kilocode/fixture/session-resume/claude.jsonl
new file mode 100644
index 00000000000..82b7a880e7c
--- /dev/null
+++ b/packages/opencode/test/kilocode/fixture/session-resume/claude.jsonl
@@ -0,0 +1,22 @@
+{"type":"user","version":"2.42.0","isSidechain":false,"message":{"id":"msg_001","role":"user","content":[{"type":"text","text":"Hello, can you help me read a file?"}]}}
+{"type":"assistant","version":"2.42.0","isSidechain":false,"message":{"id":"msg_002","role":"assistant","content":[{"type":"text","text":"Of course! Let me read that for you."},{"type":"tool_use","id":"toolu_01","name":"read","input":{"file_path":"src/index.ts"}}]}}
+{"type":"user","version":"2.42.0","isSidechain":false,"message":{"id":"msg_003","role":"user","content":[{"type":"tool_result","tool_use_id":"toolu_01","content":"export const x = 1;\nexport const y = 2;"}]}}
+{"type":"assistant","version":"2.42.0","isSidechain":false,"message":{"id":"msg_004","role":"assistant","content":[{"type":"text","text":"I can see the file contents. Now let me edit it."},{"type":"tool_use","id":"toolu_02","name":"edit","input":{"file_path":"src/index.ts","old_str":"export const x = 1;","new_str":"export const x = 42;"}},{"type":"tool_use","id":"toolu_03","name":"bash","input":{"command":"bun run typecheck"}}]}}
+{"type":"user","version":"2.42.0","isSidechain":false,"message":{"id":"msg_005","role":"user","content":[{"type":"tool_result","tool_use_id":"toolu_02","content":"File edited successfully."},{"type":"tool_result","tool_use_id":"toolu_03","content":"Typecheck passed with no errors."}]}}
+{"type":"assistant","version":"2.42.0","isSidechain":false,"message":{"id":"msg_006","role":"assistant","content":[{"type":"text","text":"The edit was applied and typecheck passed. Is there anything else?"}]}}
+{"type":"ai-title","version":"2.42.0","isSidechain":true,"message":{"id":"title_001","role":"assistant","content":[{"type":"text","text":"File read and edit session"}]}}
+{"type":"user","version":"2.42.0","isSidechain":false,"message":{"id":"msg_007","role":"user","content":[{"type":"text","text":"What is the capital of France?"}]}}
+{"type":"assistant","version":"2.42.0","isSidechain":false,"message":{"id":"msg_008","role":"assistant","content":[{"type":"thinking","thinking":"The user is asking a simple factual question. I should answer directly.","signature":"sig_test123"},{"type":"text","text":"The capital of France is Paris."}]}}
+{"type":"user","version":"2.42.0","isSidechain":false,"message":{"id":"msg_009","role":"user","content":[{"type":"text","text":"Now run a complex command with multiple tool calls."}]}}
+{"type":"assistant","version":"2.42.0","isSidechain":false,"message":{"id":"msg_010","role":"assistant","content":[{"type":"text","text":"Sure, running now."},{"type":"tool_use","id":"toolu_04","name":"bash","input":{"command":"ls -la"}},{"type":"tool_use","id":"toolu_05","name":"bash","input":{"command":"git status"}}]}}
+{"type":"user","version":"2.42.0","isSidechain":false,"message":{"id":"msg_011","role":"user","content":[{"type":"tool_result","tool_use_id":"toolu_04","content":"total 8\ndrwxr-xr-x  3 user  staff   96 Jan 1 12:00 .\ndrwxr-xr-x  5 user  staff  160 Jan 1 12:00 ..\n-rw-r--r--  1 user  staff   42 Jan 1 12:00 index.ts"}]}}
+{"type":"assistant","version":"2.42.0","isSidechain":false,"message":{"id":"msg_012","role":"assistant","content":[{"type":"text","text":"One command succeeded. The other result might have been lost."}]}}
+{"type":"user","version":"2.42.0","isSidechain":false,"message":{"id":"msg_013","role":"user","content":[{"type":"text","text":"This message repeats IDs intentionally."}]}}
+{"type":"last-prompt","version":"2.42.0","isSidechain":true,"message":{"id":"lp_001","role":"user","content":[{"type":"text","text":"This message repeats IDs intentionally."}]}}
+{"type":"assistant","version":"2.42.0","isSidechain":false,"message":{"id":"msg_014","role":"assistant","content":[{"type":"tool_use","id":"toolu_01","name":"read","input":{"file_path":"src/index.ts"}}]}}
+{"type":"user","version":"2.42.0","isSidechain":false,"message":{"id":"msg_015","role":"user","content":[{"type":"tool_result","tool_use_id":"toolu_01","content":"export const x = 42;\nexport const y = 2;"}]}}
+{"type":"assistant","version":"2.42.0","isSidechain":false,"message":{"id":"msg_016","role":"assistant","content":[{"type":"text","text":"Done reading with repeated ID."}]}}
+{"type":"user","version":"2.42.0","isSidechain":false,"message":{"id":"msg_017","role":"user","content":[{"type":"text","text":"Try something unsupported."},{"type":"server_tool_result","tool_use_id":"toolu_06","content":"raw server output"}]}}
+{"type":"assistant","version":"2.42.0","isSidechain":false,"message":{"id":"msg_018","role":"assistant","content":[{"type":"redacted_thinking","data":"encrypted_data_test"}]}}
+{"type":"assistant","version":"2.42.0","isSidechain":false,"message":{"id":"msg_019","role":"assistant","content":[{"type":"custom_block","custom_field":"some_value"}]}}
+{"type":"assistant","version":"2.42.0","isSidechain":false,"message":{"id":"msg_020","role":"assistant","content":[{"type":"tool_use","id":"toolu_06","name":"search","input":{"query":"test"}}]}}
diff --git a/packages/opencode/test/kilocode/fixture/session-resume/codex.jsonl b/packages/opencode/test/kilocode/fixture/session-resume/codex.jsonl
new file mode 100644
index 00000000000..67b3133b641
--- /dev/null
+++ b/packages/opencode/test/kilocode/fixture/session-resume/codex.jsonl
@@ -0,0 +1,27 @@
+{"type":"session_meta","payload":{"cli_version":"0.8.0","cwd":"/Users/test/project","model_provider":"openai","session_id":"ses_test001"}}
+{"type":"response_item","payload":{"id":"item_001","type":"message","role":"user","content":[{"type":"input_text","text":"Read src/index.ts and then edit it."}]}}
+{"type":"response_item","payload":{"id":"item_002","type":"function_call","call_id":"call_01","name":"read","arguments":"{\"file_path\":\"src/index.ts\"}"}}
+{"type":"response_item","payload":{"id":"item_003","type":"function_call_output","call_id":"call_01","output":"export const x = 1;\nexport const y = 2;"}}
+{"type":"response_item","payload":{"id":"item_004","type":"message","role":"assistant","content":[{"type":"output_text","text":"Done reading. Now editing."}]}}
+{"type":"response_item","payload":{"id":"item_005","type":"function_call","call_id":"call_02","name":"edit","arguments":"{\"file_path\":\"src/index.ts\",\"old_str\":\"export const x = 1;\",\"new_str\":\"export const x = 42;\"}"}}
+{"type":"response_item","payload":{"id":"item_006","type":"function_call","call_id":"call_03","name":"bash","arguments":"{\"command\":\"bun run typecheck\"}"}}
+{"type":"response_item","payload":{"id":"item_007","type":"function_call_output","call_id":"call_02","output":"File edited successfully."}}
+{"type":"response_item","payload":{"id":"item_008","type":"function_call_output","call_id":"call_03","output":"Typecheck passed with no errors."}}
+{"type":"response_item","payload":{"id":"item_009","type":"message","role":"assistant","content":[{"type":"output_text","text":"The edit was applied and typecheck passed."}]}}
+{"type":"turn_context","payload":{}}
+{"type":"response_item","payload":{"id":"item_010","type":"message","role":"user","content":[{"type":"input_text","text":"What is the capital of France?"}]}}
+{"type":"response_item","payload":{"id":"item_011","type":"message","role":"assistant","content":[{"type":"output_text","text":"The capital of France is Paris."}]}}
+{"type":"response_item","payload":{"id":"item_012","type":"message","role":"user","content":[{"type":"input_text","text":"Now run multiple commands."}]}}
+{"type":"response_item","payload":{"id":"item_013","type":"function_call","call_id":"call_04","name":"bash","arguments":"{\"command\":\"ls -la\"}"}}
+{"type":"response_item","payload":{"id":"item_014","type":"function_call","call_id":"call_05","name":"bash","arguments":"{\"command\":\"git status\"}"}}
+{"type":"response_item","payload":{"id":"item_015","type":"function_call_output","call_id":"call_04","output":"total 8\ndrwxr-xr-x  3 user  staff   96 Jan 1 12:00 ."}}
+{"type":"response_item","payload":{"id":"item_016","type":"message","role":"user","content":[{"type":"input_text","text":"One result was lost. Continue."}]}}
+{"type":"response_item","payload":{"id":"item_017","type":"message","role":"assistant","content":[{"type":"output_text","text":"Only one command result arrived."}]}}
+{"type":"response_item","payload":{"id":"item_018","type":"message","role":"user","content":[{"type":"input_text","text":"Repeated call IDs."}]}}
+{"type":"response_item","payload":{"id":"item_019","type":"function_call","call_id":"call_01","name":"read","arguments":"{\"file_path\":\"src/index.ts\"}"}}
+{"type":"response_item","payload":{"id":"item_020","type":"function_call_output","call_id":"call_01","output":"export const x = 42;\nexport const y = 2;"}}
+{"type":"response_item","payload":{"id":"item_021","type":"message","role":"assistant","content":[{"type":"output_text","text":"Done with repeated call ID."}]}}
+{"type":"response_item","payload":{"id":"item_022","type":"message","role":"user","content":[{"type":"input_text","text":"Unsupported content."}]}}
+{"type":"response_item","payload":{"id":"item_023","type":"reasoning","summary":[]}}
+{"type":"event_msg","payload":{}}
+{"type":"response_item","payload":{"id":"item_024","type":"message","role":"assistant","content":[]}}
\ No newline at end of file
diff --git a/packages/opencode/test/kilocode/npm-publish.test.ts b/packages/opencode/test/kilocode/npm-publish.test.ts
index 33318925ce7..62e94349865 100644
--- a/packages/opencode/test/kilocode/npm-publish.test.ts
+++ b/packages/opencode/test/kilocode/npm-publish.test.ts
@@ -1,16 +1,6 @@
 import { describe, expect, test } from "bun:test"
 import { NpmPublish } from "../../script/kilocode/npm-publish"
 
-describe("npm publish aliases", () => {
-  test("promotes stable releases to the rc channel", () => {
-    expect(NpmPublish.aliases("latest")).toEqual(["rc"])
-  })
-
-  test("does not promote prereleases", () => {
-    expect(NpmPublish.aliases("rc")).toEqual([])
-  })
-})
-
 describe("npm publish retry", () => {
   test("returns after the first successful attempt", async () => {
     const calls = { run: 0, exists: 0, sleep: 0 }
diff --git a/packages/opencode/test/kilocode/provider/session-resume-cache.test.ts b/packages/opencode/test/kilocode/provider/session-resume-cache.test.ts
new file mode 100644
index 00000000000..a7415d0ce85
--- /dev/null
+++ b/packages/opencode/test/kilocode/provider/session-resume-cache.test.ts
@@ -0,0 +1,245 @@
+import { describe, expect, test } from "bun:test"
+import path from "node:path"
+import { SessionResume } from "../../../src/kilocode/session-resume"
+import { ProviderTransform } from "../../../src/provider/transform"
+import { MessageV2 } from "../../../src/session/message-v2"
+import { ProviderV2 } from "@opencode-ai/core/provider"
+import { ModelV2 } from "@opencode-ai/core/model"
+import type { Provider } from "../../../src/provider/provider"
+import type { Part as V1Part, WithParts } from "@opencode-ai/core/v1/session"
+
+function cacheType(message: { providerOptions?: unknown }) {
+  const anthropic = message.providerOptions as { anthropic?: { cacheControl?: { type?: unknown } } } | undefined
+  return anthropic?.anthropic?.cacheControl?.type
+}
+
+// ── Fixtures ──────────────────────────────────────────────────────────────
+
+const claudeFixture = () =>
+  Bun.file(path.join(__dirname, "../fixture/session-resume/claude.jsonl")).text()
+
+const codexFixture = () =>
+  Bun.file(path.join(__dirname, "../fixture/session-resume/codex.jsonl")).text()
+
+// ── Model helpers ────────────────────────────────────────────────────────
+
+function openaiModel(id: string, opts: { reasoning?: boolean } = {}): Provider.Model {
+  return {
+    id: ModelV2.ID.make(id),
+    providerID: ProviderV2.ID.make("openai"),
+    api: { id, url: "https://api.openai.com/v1", npm: "@ai-sdk/openai" },
+    name: "OpenAI Test",
+    capabilities: {
+      temperature: true,
+      reasoning: opts.reasoning ?? false,
+      attachment: true,
+      toolcall: true,
+      input: { text: true, audio: false, image: true, video: false, pdf: false },
+      output: { text: true, audio: false, image: false, video: false, pdf: false },
+      interleaved: false,
+    },
+    cost: {
+      input: 0,
+      output: 0,
+      cache: { read: 0, write: 0 },
+    },
+    limit: { context: 128000, output: 32000 },
+    status: "active" as const,
+    options: {},
+    headers: {},
+    release_date: "2025-01-01",
+  }
+}
+
+function anthropicModel(id: string): Provider.Model {
+  return {
+    id: ModelV2.ID.make(id),
+    providerID: ProviderV2.ID.make("anthropic"),
+    api: { id, url: "https://api.anthropic.com/v1", npm: "@ai-sdk/anthropic" },
+    name: "Anthropic Test",
+    capabilities: {
+      temperature: true,
+      reasoning: true,
+      attachment: true,
+      toolcall: true,
+      input: { text: true, audio: false, image: true, video: false, pdf: true },
+      output: { text: true, audio: false, image: false, video: false, pdf: false },
+      interleaved: false,
+    },
+    cost: {
+      input: 0,
+      output: 0,
+      cache: { read: 0, write: 0 },
+    },
+    limit: { context: 200000, output: 32000 },
+    status: "active" as const,
+    options: {},
+    headers: {},
+    release_date: "2025-01-01",
+  }
+}
+
+// ── Transcript helpers ───────────────────────────────────────────────────
+
+const base = {
+  sessionID: "ses_cache",
+  agent: "build",
+  providerID: "openai",
+  modelID: "gpt-5",
+  directory: "/test",
+  worktree: "/test",
+}
+
+function castToWithParts(mapped: SessionResume.MappedMessage[]): WithParts[] {
+  return mapped.map((m) => ({
+    info: m.info as WithParts["info"],
+    parts: m.parts as V1Part[],
+  }))
+}
+
+// ── Helper: parse fixture through the full resume pipeline ────────────────
+
+/** Parse a fixture JSONL, map through SessionResume, convert to model messages. */
+async function buildModelMessages(model: Provider.Model, fixtureName: "claude" | "codex") {
+  const content = fixtureName === "claude" ? await claudeFixture() : await codexFixture()
+  const transcript = SessionResume.parseLines(content)
+  const { messages } = SessionResume.mapTranscript(transcript, {
+    ...base,
+    ...(transcript.sourceModel ? { sourceModel: transcript.sourceModel } : {}),
+  })
+  const msgs = castToWithParts(messages)
+  return MessageV2.toModelMessages(msgs, model)
+}
+
+// ── Cache-proof tests ─────────────────────────────────────────────────────
+
+describe("MessageV2.toModelMessages + ProviderTransform cache continuity", () => {
+  for (const fixture of ["claude", "codex"] as const) {
+    test(`keeps the ${fixture} imported prefix and session cache key across two OpenAI requests`, async () => {
+      const model = openaiModel("gpt-5")
+      const imported = await buildModelMessages(model, fixture)
+      const firstOptions = ProviderTransform.options({ model, sessionID: base.sessionID })
+      const laterOptions = ProviderTransform.options({ model, sessionID: base.sessionID })
+      const firstInput = [...structuredClone(imported), { role: "user" as const, content: "Continue from import." }]
+      const laterInput = [
+        ...structuredClone(imported),
+        { role: "user" as const, content: "Continue from import." },
+        { role: "assistant" as const, content: "The imported history is available." },
+        { role: "user" as const, content: "Use a different model for this next turn." },
+      ]
+      const first = ProviderTransform.message(firstInput, model, firstOptions)
+      const later = ProviderTransform.message(laterInput, model, laterOptions)
+
+      expect(firstOptions.promptCacheKey).toBe(base.sessionID)
+      expect(laterOptions.promptCacheKey).toBe(base.sessionID)
+      expect(JSON.stringify(first.slice(0, imported.length))).toBe(JSON.stringify(later.slice(0, imported.length)))
+    })
+  }
+
+  test("sets store:false for OpenAI models", () => {
+    const model = openaiModel("gpt-5")
+    const opts = ProviderTransform.options({ model, sessionID: "ses_test" })
+    expect(opts.store).toBe(false)
+  })
+
+
+  test("fixture-derived messages preserve transcript text exactly (claude fixture)", async () => {
+    const model = openaiModel("gpt-5")
+    const modelMsgs = await buildModelMessages(model, "claude")
+    const opts = ProviderTransform.options({ model, sessionID: base.sessionID })
+    const transformed = ProviderTransform.message(modelMsgs, model, opts)
+
+    expect(transformed.length).toBeGreaterThan(0)
+    const raw = JSON.stringify(transformed)
+    // First user message from the claude fixture
+    expect(raw).toContain("Hello, can you help me read a file")
+    // A later user message from the fixture
+    expect(raw).toContain("What is the capital of France")
+  })
+
+  test("fixture-derived messages preserve transcript text exactly (codex fixture)", async () => {
+    const model = openaiModel("gpt-5")
+    const modelMsgs = await buildModelMessages(model, "codex")
+    const opts = ProviderTransform.options({ model, sessionID: base.sessionID })
+    const transformed = ProviderTransform.message(modelMsgs, model, opts)
+
+    expect(transformed.length).toBeGreaterThan(0)
+    const raw = JSON.stringify(transformed)
+    // First user message from the codex fixture
+    expect(raw).toContain("Read src/index.ts and then edit it")
+    expect(raw).toContain("What is the capital of France")
+  })
+})
+
+describe("ProviderTransform.message – Anthropic caching", () => {
+  const SYSTEM = { role: "system" as const, content: "You are a test assistant." }
+
+  test("marks the prepended system message with cache control (claude fixture)", async () => {
+    const model = anthropicModel("claude-sonnet-4-20250514")
+    const modelMsgs = await buildModelMessages(model, "claude")
+    const opts = ProviderTransform.options({ model, sessionID: base.sessionID })
+
+    const withSystem = [SYSTEM, ...modelMsgs]
+    const transformed = ProviderTransform.message(withSystem, model, opts)
+
+    const sys = transformed.find((m) => m.role === "system")
+    expect(sys).toBeDefined()
+    expect(cacheType(sys!)).toBe("ephemeral")
+  })
+
+  test("marks exactly the final two non-system messages with cache control (claude fixture)", async () => {
+    const model = anthropicModel("claude-sonnet-4-20250514")
+    const modelMsgs = await buildModelMessages(model, "claude")
+    const opts = ProviderTransform.options({ model, sessionID: base.sessionID })
+
+    const withSystem = [SYSTEM, ...modelMsgs]
+    const transformed = ProviderTransform.message(withSystem, model, opts)
+
+    const nonSystem = transformed.filter((m) => m.role !== "system")
+    expect(nonSystem.length).toBeGreaterThanOrEqual(2)
+
+    const last = nonSystem[nonSystem.length - 1]
+    const prev = nonSystem[nonSystem.length - 2]
+    expect(cacheType(last)).toBe("ephemeral")
+    expect(cacheType(prev)).toBe("ephemeral")
+
+    // No other non-system message carries cache control
+    for (let i = 0; i < nonSystem.length - 2; i++) {
+      expect(cacheType(nonSystem[i])).toBeUndefined()
+    }
+  })
+
+  test("marks the prepended system message with cache control (codex fixture)", async () => {
+    const model = anthropicModel("claude-sonnet-4-20250514")
+    const modelMsgs = await buildModelMessages(model, "codex")
+    const opts = ProviderTransform.options({ model, sessionID: base.sessionID })
+
+    const withSystem = [SYSTEM, ...modelMsgs]
+    const transformed = ProviderTransform.message(withSystem, model, opts)
+
+    const sys = transformed.find((m) => m.role === "system")
+    expect(sys).toBeDefined()
+    expect(cacheType(sys!)).toBe("ephemeral")
+  })
+
+  test("marks exactly the final two non-system messages with cache control (codex fixture)", async () => {
+    const model = anthropicModel("claude-sonnet-4-20250514")
+    const modelMsgs = await buildModelMessages(model, "codex")
+    const opts = ProviderTransform.options({ model, sessionID: base.sessionID })
+
+    const withSystem = [SYSTEM, ...modelMsgs]
+    const transformed = ProviderTransform.message(withSystem, model, opts)
+
+    const nonSystem = transformed.filter((m) => m.role !== "system")
+    expect(nonSystem.length).toBeGreaterThanOrEqual(2)
+
+    const last = nonSystem[nonSystem.length - 1]
+    const prev = nonSystem[nonSystem.length - 2]
+    expect(cacheType(last)).toBe("ephemeral")
+    expect(cacheType(prev)).toBe("ephemeral")
+
+    for (let i = 0; i < nonSystem.length - 2; i++) {
+      expect(cacheType(nonSystem[i])).toBeUndefined()
+    }
+  })
+})
diff --git a/packages/opencode/test/kilocode/server/httpapi-exercise-scenarios.ts b/packages/opencode/test/kilocode/server/httpapi-exercise-scenarios.ts
index 2e3e6c4f9ce..85bbd555cc7 100644
--- a/packages/opencode/test/kilocode/server/httpapi-exercise-scenarios.ts
+++ b/packages/opencode/test/kilocode/server/httpapi-exercise-scenarios.ts
@@ -389,6 +389,7 @@ export const kiloScenarios: Scenario[] = [
     .status(401),
   http.protected.get("/kilo/notifications", "kilo.notifications").json(200, array),
   http.protected.get("/kilo/models/images", "kilo.models.images").probe({ path: "/path" }).status(401),
+  http.protected.get("/kilo/models/transcriptions", "kilo.models.transcriptions").probe({ path: "/path" }).status(401),
   http.protected
     .post("/kilo/organization", "kilo.organization.set")
     .at((ctx) => ({ path: "/kilo/organization", headers: ctx.headers(), body: { organizationId: null } }))
diff --git a/packages/opencode/test/kilocode/server/httpapi-public.test.ts b/packages/opencode/test/kilocode/server/httpapi-public.test.ts
index 2dc91f2f3a8..0d87c0bfe70 100644
--- a/packages/opencode/test/kilocode/server/httpapi-public.test.ts
+++ b/packages/opencode/test/kilocode/server/httpapi-public.test.ts
@@ -237,4 +237,13 @@ describe("Kilo PublicApi OpenAPI contract", () => {
     const schema = body?.content?.["application/json"]?.schema
     expect(schema?.properties?.prompt).toEqual({ type: "string" })
   })
+
+  test("documents the transcription model catalog route", () => {
+    const spec = OpenApi.fromApi(PublicApi)
+    const route = spec.paths[KiloGatewayPaths.transcriptionModels]?.get
+    const query = (route?.parameters as Parameter[] | undefined)?.map((item) => item.name)
+
+    expect(query).toEqual(["directory", "workspace"])
+    expect(route?.responses?.["200"]?.content?.["application/json"]?.schema).toMatchObject({ type: "array" })
+  })
 })
diff --git a/packages/opencode/test/kilocode/session-resume-integration.test.ts b/packages/opencode/test/kilocode/session-resume-integration.test.ts
new file mode 100644
index 00000000000..9458dd4489f
--- /dev/null
+++ b/packages/opencode/test/kilocode/session-resume-integration.test.ts
@@ -0,0 +1,1151 @@
+import path from "node:path"
+import os from "node:os"
+import fs from "node:fs"
+import { expect } from "bun:test"
+import { Effect, Exit, Layer, Schema } from "effect"
+import { FetchHttpClient } from "effect/unstable/http"
+import { NodeFileSystem } from "@effect/platform-node"
+import { CrossSpawnSpawner } from "@opencode-ai/core/cross-spawn-spawner"
+import { RepositoryCache } from "@opencode-ai/core/repository-cache"
+import { Database } from "@opencode-ai/core/database/database"
+import { Ripgrep } from "@opencode-ai/core/ripgrep"
+import { Agent as AgentSvc } from "../../src/agent/agent"
+import { Auth } from "../../src/auth"
+import { BackgroundJob } from "../../src/background/job"
+import { Bus } from "../../src/bus"
+import { Command } from "../../src/command"
+import { Config } from "../../src/config/config"
+import { RuntimeFlags } from "../../src/effect/runtime-flags"
+import { EventV2Bridge } from "../../src/event-v2-bridge"
+import { Env } from "../../src/env"
+import { FSUtil } from "@opencode-ai/core/fs-util"
+import { Format } from "../../src/format"
+import { Git } from "../../src/git"
+import { Image } from "../../src/image/image"
+import { LSP } from "../../src/lsp/lsp"
+import { MCP } from "../../src/mcp"
+import { Permission } from "../../src/permission"
+import { Plugin } from "../../src/plugin"
+import { Provider as ProviderSvc } from "../../src/provider/provider"
+import { Question } from "../../src/question"
+import { SessionCompaction } from "../../src/session/compaction"
+import { Instruction } from "../../src/session/instruction"
+import { LLM } from "../../src/session/llm"
+import { SessionProcessor } from "../../src/session/processor"
+import { SessionPrompt } from "../../src/session/prompt"
+import { SessionRevert } from "../../src/session/revert"
+import { SessionRunState } from "../../src/session/run-state"
+import { Session } from "../../src/session/session"
+import { SessionStatus } from "../../src/session/status"
+import { SystemPrompt } from "../../src/session/system"
+import { SessionSummary } from "../../src/session/summary"
+import { Todo } from "../../src/session/todo"
+import { Skill } from "../../src/skill"
+import { Snapshot } from "../../src/snapshot"
+import { SyncEvent } from "../../src/sync"
+import { ToolRegistry } from "../../src/tool/registry"
+import { Truncate } from "../../src/tool/truncate"
+import { KiloSessions } from "../../src/kilo-sessions/kilo-sessions"
+import { SessionResume } from "../../src/kilocode/session-resume"
+import { SessionID, MessageID, PartID } from "../../src/session/schema"
+import { MemoryService } from "@kilocode/kilo-memory/effect/service"
+import { provideTmpdirServer, TestInstance, disposeAllInstances } from "../fixture/fixture"
+import { testEffect } from "../lib/effect"
+import { TestLLMServer } from "../lib/llm-server"
+import { ProviderV2 } from "@opencode-ai/core/provider"
+import { ModelV2 } from "@opencode-ai/core/model"
+import { SessionV1 } from "@opencode-ai/core/v1/session"
+
+// ── Test layer ──────────────────────────────────────────────────────────
+
+const ref = {
+  providerID: ProviderV2.ID.make("test"),
+  modelID: ModelV2.ID.make("test-model"),
+}
+
+const agent: AgentSvc.Info = {
+  name: "build",
+  mode: "primary",
+  native: true,
+  permission: Permission.fromConfig({ "*": "allow" }),
+  model: ref,
+  options: {},
+}
+
+const fastAgents = Layer.mock(AgentSvc.Service)({
+  get: () => Effect.succeed(agent),
+  list: () => Effect.succeed([agent]),
+  defaultInfo: () => Effect.succeed(agent),
+  defaultAgent: () => Effect.succeed(agent.name),
+  guardRequirements: () => Effect.void,
+})
+
+const summary = Layer.succeed(
+  SessionSummary.Service,
+  SessionSummary.Service.of({
+    summarize: () => Effect.void,
+    diff: () => Effect.succeed([]),
+    computeDiff: () => Effect.succeed([]),
+  }),
+)
+
+const mcp = Layer.succeed(
+  MCP.Service,
+  MCP.Service.of({
+    status: () => Effect.succeed({}),
+    clients: () => Effect.succeed({}),
+    tools: () => Effect.succeed({}),
+    prompts: () => Effect.succeed({}),
+    resources: () => Effect.succeed({}),
+    add: () => Effect.succeed({ status: { status: "disabled" as const } }),
+    connect: () => Effect.void,
+    disconnect: () => Effect.void,
+    getPrompt: () => Effect.succeed(undefined),
+    readResource: () => Effect.succeed(undefined),
+    startAuth: () => Effect.die("unexpected MCP auth"),
+    authenticate: () => Effect.die("unexpected MCP auth"),
+    finishAuth: () => Effect.die("unexpected MCP auth"),
+    removeAuth: () => Effect.void,
+    supportsOAuth: () => Effect.succeed(false),
+    hasStoredTokens: () => Effect.succeed(false),
+    getAuthStatus: () => Effect.succeed("not_authenticated" as const),
+  }),
+)
+
+const lsp = Layer.succeed(
+  LSP.Service,
+  LSP.Service.of({
+    init: () => Effect.void,
+    status: () => Effect.succeed([]),
+    hasClients: () => Effect.succeed(false),
+    touchFile: () => Effect.void,
+    diagnostics: () => Effect.succeed({}),
+    hover: () => Effect.succeed(undefined),
+    definition: () => Effect.succeed([]),
+    references: () => Effect.succeed([]),
+    implementation: () => Effect.succeed([]),
+    documentSymbol: () => Effect.succeed([]),
+    workspaceSymbol: () => Effect.succeed([]),
+    prepareCallHierarchy: () => Effect.succeed([]),
+    incomingCalls: () => Effect.succeed([]),
+    outgoingCalls: () => Effect.succeed([]),
+  }),
+)
+
+const status = SessionStatus.layer.pipe(Layer.provideMerge(EventV2Bridge.defaultLayer))
+const run = SessionRunState.layer.pipe(Layer.provide(status))
+const infra = Layer.mergeAll(NodeFileSystem.layer, CrossSpawnSpawner.defaultLayer)
+
+const cfg = {
+  provider: {
+    test: {
+      name: "Test",
+      id: "test",
+      env: [],
+      npm: "@ai-sdk/openai-compatible",
+      models: {
+        "test-model": {
+          id: "test-model",
+          name: "Test Model",
+          attachment: false,
+          reasoning: false,
+          temperature: false,
+          tool_call: true,
+          release_date: "2025-01-01",
+          limit: { context: 100000, output: 10000 },
+          cost: { input: 0, output: 0 },
+          options: {},
+        },
+      },
+      options: {
+        apiKey: "test-key",
+        baseURL: "http://localhost:1/v1",
+      },
+    },
+  },
+}
+
+function providerCfg(url: string) {
+  return {
+    ...cfg,
+    provider: {
+      ...cfg.provider,
+      test: {
+        ...cfg.provider.test,
+        options: {
+          ...cfg.provider.test.options,
+          baseURL: url,
+        },
+      },
+    },
+  }
+}
+
+function makePrompt() {
+  const deps = Layer.mergeAll(
+    Session.defaultLayer,
+    Snapshot.defaultLayer,
+    LLM.defaultLayer,
+    Env.defaultLayer,
+    fastAgents,
+    Command.defaultLayer,
+    Permission.defaultLayer,
+    Plugin.defaultLayer,
+    Config.defaultLayer,
+    ProviderSvc.defaultLayer,
+    lsp,
+    mcp,
+    FSUtil.defaultLayer,
+    BackgroundJob.defaultLayer,
+    status,
+    Database.defaultLayer,
+    EventV2Bridge.defaultLayer,
+    Bus.layer,
+    MemoryService.layer,
+  ).pipe(Layer.provideMerge(infra))
+  const question = Question.layer.pipe(Layer.provideMerge(deps))
+  const todo = Todo.layer.pipe(Layer.provideMerge(deps))
+  const registry = ToolRegistry.layer.pipe(
+    Layer.provide(Skill.defaultLayer),
+    Layer.provide(FetchHttpClient.layer),
+    Layer.provide(CrossSpawnSpawner.defaultLayer),
+    Layer.provide(Git.defaultLayer),
+    Layer.provide(Ripgrep.defaultLayer),
+    Layer.provide(RepositoryCache.defaultLayer),
+    Layer.provide(Format.defaultLayer),
+    Layer.provide(RuntimeFlags.layer({ experimentalEventSystem: true })),
+    Layer.provide(Auth.defaultLayer),
+    Layer.provide(KiloSessions.testLayer),
+    Layer.provideMerge(todo),
+    Layer.provideMerge(question),
+    Layer.provideMerge(deps),
+  )
+  const trunc = Truncate.layer.pipe(Layer.provideMerge(deps))
+  const proc = SessionProcessor.layer.pipe(
+    Layer.provide(summary),
+    Layer.provide(Image.defaultLayer),
+    Layer.provide(RuntimeFlags.layer({ experimentalEventSystem: true })),
+    Layer.provideMerge(deps),
+  )
+  const compact = SessionCompaction.layer.pipe(
+    Layer.provide(RuntimeFlags.layer({ experimentalEventSystem: true })),
+    Layer.provideMerge(proc),
+    Layer.provideMerge(deps),
+  )
+  return SessionPrompt.layer.pipe(
+    Layer.provide(SessionRevert.defaultLayer),
+    Layer.provide(Image.defaultLayer),
+    Layer.provide(summary),
+    Layer.provideMerge(run),
+    Layer.provideMerge(compact),
+    Layer.provideMerge(proc),
+    Layer.provideMerge(registry),
+    Layer.provideMerge(trunc),
+    Layer.provideMerge(question),
+    Layer.provide(Instruction.defaultLayer),
+    Layer.provide(SystemPrompt.defaultLayer),
+    Layer.provide(RuntimeFlags.layer({ experimentalEventSystem: true })),
+    Layer.provideMerge(deps),
+    Layer.provide(summary),
+  )
+}
+
+// Picker tests need a Question service mock that auto-selects the first
+// option instead of blocking on the question UI.
+function makePromptWithAutoPick() {
+  const deps = Layer.mergeAll(
+    Session.defaultLayer,
+    Snapshot.defaultLayer,
+    LLM.defaultLayer,
+    Env.defaultLayer,
+    fastAgents,
+    Command.defaultLayer,
+    Permission.defaultLayer,
+    Plugin.defaultLayer,
+    Config.defaultLayer,
+    ProviderSvc.defaultLayer,
+    lsp,
+    mcp,
+    FSUtil.defaultLayer,
+    BackgroundJob.defaultLayer,
+    status,
+    Database.defaultLayer,
+    EventV2Bridge.defaultLayer,
+    Bus.layer,
+    MemoryService.layer,
+  ).pipe(Layer.provideMerge(infra))
+  const question = Layer.mock(Question.Service, {
+    ask: (input) =>
+      Effect.gen(function* () {
+        const q = input.questions[0]
+        if (!q) return [] as readonly string[][]
+        const label = q.options?.[0]?.label ?? ""
+        return [[label]]
+      }),
+  })
+  const todo = Todo.layer.pipe(Layer.provideMerge(deps))
+  const registry = ToolRegistry.layer.pipe(
+    Layer.provide(Skill.defaultLayer),
+    Layer.provide(FetchHttpClient.layer),
+    Layer.provide(CrossSpawnSpawner.defaultLayer),
+    Layer.provide(Git.defaultLayer),
+    Layer.provide(Ripgrep.defaultLayer),
+    Layer.provide(RepositoryCache.defaultLayer),
+    Layer.provide(Format.defaultLayer),
+    Layer.provide(RuntimeFlags.layer({ experimentalEventSystem: true })),
+    Layer.provide(Auth.defaultLayer),
+    Layer.provide(KiloSessions.testLayer),
+    Layer.provideMerge(todo),
+    Layer.provideMerge(question),
+    Layer.provideMerge(deps),
+  )
+  const trunc = Truncate.layer.pipe(Layer.provideMerge(deps))
+  const proc = SessionProcessor.layer.pipe(
+    Layer.provide(summary),
+    Layer.provide(Image.defaultLayer),
+    Layer.provide(RuntimeFlags.layer({ experimentalEventSystem: true })),
+    Layer.provideMerge(deps),
+  )
+  const compact = SessionCompaction.layer.pipe(
+    Layer.provide(RuntimeFlags.layer({ experimentalEventSystem: true })),
+    Layer.provideMerge(proc),
+    Layer.provideMerge(deps),
+  )
+  return SessionPrompt.layer.pipe(
+    Layer.provide(SessionRevert.defaultLayer),
+    Layer.provide(Image.defaultLayer),
+    Layer.provide(summary),
+    Layer.provideMerge(run),
+    Layer.provideMerge(compact),
+    Layer.provideMerge(proc),
+    Layer.provideMerge(registry),
+    Layer.provideMerge(trunc),
+    Layer.provideMerge(question),
+    Layer.provide(Instruction.defaultLayer),
+    Layer.provide(SystemPrompt.defaultLayer),
+    Layer.provide(RuntimeFlags.layer({ experimentalEventSystem: true })),
+    Layer.provideMerge(deps),
+    Layer.provide(summary),
+  )
+}
+
+function makeHttp() {
+  return Layer.mergeAll(TestLLMServer.layer, makePrompt())
+}
+const it = testEffect(makeHttp())
+
+function makeHttpWithAutoPick() {
+  return Layer.mergeAll(TestLLMServer.layer, makePromptWithAutoPick())
+}
+const itPicker = testEffect(makeHttpWithAutoPick())
+
+const writeText = Effect.fn("test.writeText")(function* (file: string, text: string) {
+  const fsys = yield* FSUtil.Service
+  yield* fsys.writeWithDirs(file, text)
+})
+
+const writeConfig = Effect.fn("test.writeConfig")(function* (dir: string, config: Partial<Config.Info>) {
+  yield* writeText(
+    path.join(dir, "opencode.json"),
+    JSON.stringify({ $schema: "https://app.kilo.ai/config.json", ...config }),
+  )
+})
+
+const useServerConfig = Effect.fn("test.useServerConfig")(function* (config: (url: string) => Partial<Config.Info>) {
+  const { directory: dir } = yield* TestInstance
+  const llm = yield* TestLLMServer
+  yield* writeConfig(dir, config(llm.url))
+  return { dir, llm }
+})
+
+const boot = Effect.fn("test.boot")(function* (input?: { title?: string }) {
+  const prompt = yield* SessionPrompt.Service
+  const sessions = yield* Session.Service
+  const chat = yield* sessions.create(input ?? {})
+  return { prompt, sessions, chat }
+})
+
+// ── Claude fixture helpers ─────────────────────────────────────────────
+
+const claudeFixture = () =>
+  Bun.file(path.join(__dirname, "fixture/session-resume/claude.jsonl")).text()
+
+const claudeInvalidVersion = `{"type":"user","version":"3.0.0","isSidechain":false,"message":{"id":"msg_001","role":"user","content":[{"type":"text","text":"Hello"}]}}`
+
+const fixtureUUID = "550e8400-e29b-41d4-a716-446655440000"
+
+function claudeSlug(cwd: string) {
+  return SessionResume.claudeProjectSlug(cwd)
+}
+
+function claudeSessionFile(cwd: string, id: string) {
+  return path.join(os.homedir(), ".claude", "projects", claudeSlug(cwd), `${id}.jsonl`)
+}
+
+/**
+ * Write a Claude session fixture into the home-directory path that handleResume
+ * discovers. Returns a disposable effect that removes the file + directory.
+ */
+const withClaudeFixture = (cwd: string, content: string, id: string) =>
+  Effect.acquireRelease(
+    Effect.gen(function* () {
+      const file = claudeSessionFile(cwd, id)
+      yield* writeText(file, content)
+      return file
+    }),
+    (file) =>
+      Effect.gen(function* () {
+        fs.rmSync(path.dirname(file), { recursive: true, force: true })
+      }),
+  )
+
+// ── Helper: read messages for a session ────────────────────────────────
+
+const sessionMessages = (sessionID: SessionID) =>
+  Effect.gen(function* () {
+    const sessions = yield* Session.Service
+    return yield* sessions.messages({ sessionID })
+  })
+
+// ── Tests ──────────────────────────────────────────────────────────────
+
+it.instance(
+  "explicit ID import produces normal session history",
+  () =>
+    Effect.gen(function* () {
+      const { dir } = yield* useServerConfig(providerCfg)
+      const { prompt, chat } = yield* boot()
+      const content = yield* Effect.promise(() => claudeFixture())
+      yield* withClaudeFixture(dir, content, fixtureUUID)
+
+      yield* prompt.command({
+        sessionID: chat.id,
+        command: "resume-claude",
+        arguments: fixtureUUID,
+        agent: "build",
+      })
+
+      const msgs = yield* sessionMessages(chat.id)
+      // The fixture has 13 steps: 7 user + 6 assistant
+      expect(msgs.length).toBeGreaterThanOrEqual(10)
+
+      // First message must be user
+      expect(msgs[0].info.role).toBe("user")
+      // Last message must be assistant with the import notice
+      const last = msgs[msgs.length - 1]
+      expect(last.info.role).toBe("assistant")
+      const text = last.parts.find((p) => p.type === "text")
+      expect(text?.type === "text" && text.text).toContain("imported from an external session")
+    }),
+  { config: cfg },
+  30_000,
+)
+
+it.instance(
+  "imported assistant messages carry complete fields",
+  () =>
+    Effect.gen(function* () {
+      const { dir } = yield* useServerConfig(providerCfg)
+      const { prompt, chat } = yield* boot()
+      const content = yield* Effect.promise(() => claudeFixture())
+      yield* withClaudeFixture(dir, content, fixtureUUID)
+
+      yield* prompt.command({
+        sessionID: chat.id,
+        command: "resume-claude",
+        arguments: fixtureUUID,
+        agent: "build",
+      })
+
+      const msgs = yield* sessionMessages(chat.id)
+
+      // All assistant messages must have non-empty modelID
+      for (const msg of msgs) {
+        if (msg.info.role === "assistant") {
+          expect(msg.info.providerID).toBeString()
+          expect(msg.info.modelID).toBeString()
+          expect(msg.info.finish).toBe("stop")
+          expect(msg.info.agent).toBe("build")
+        }
+      }
+    }),
+  { config: cfg },
+  30_000,
+)
+
+it.instance(
+  "imported session contains tool states with completed and error status",
+  () =>
+    Effect.gen(function* () {
+      const { dir } = yield* useServerConfig(providerCfg)
+      const { prompt, chat } = yield* boot()
+      const content = yield* Effect.promise(() => claudeFixture())
+      yield* withClaudeFixture(dir, content, fixtureUUID)
+
+      yield* prompt.command({
+        sessionID: chat.id,
+        command: "resume-claude",
+        arguments: fixtureUUID,
+        agent: "build",
+      })
+
+      const msgs = yield* sessionMessages(chat.id)
+
+      const tools = msgs.flatMap((msg) => msg.parts.filter((p) => p.type === "tool"))
+      expect(tools.length).toBeGreaterThanOrEqual(4)
+
+      const completed = tools.filter((t) => (t as unknown as { state: { status: string } }).state.status === "completed")
+      expect(completed.length).toBeGreaterThanOrEqual(2)
+
+      const errors = tools.filter((t) => (t as unknown as { state: { status: string } }).state.status === "error")
+      expect(errors.length).toBeGreaterThanOrEqual(1)
+    }),
+  { config: cfg },
+  30_000,
+)
+
+it.instance(
+  "terminal import notice appears on the final assistant",
+  () =>
+    Effect.gen(function* () {
+      const { dir } = yield* useServerConfig(providerCfg)
+      const { prompt, chat } = yield* boot()
+      const content = yield* Effect.promise(() => claudeFixture())
+      yield* withClaudeFixture(dir, content, fixtureUUID)
+
+      yield* prompt.command({
+        sessionID: chat.id,
+        command: "resume-claude",
+        arguments: fixtureUUID,
+        agent: "build",
+      })
+
+      const msgs = yield* sessionMessages(chat.id)
+      const last = msgs[msgs.length - 1]
+      expect(last.info.role).toBe("assistant")
+
+      const noticePart = last.parts.find((p) => p.type === "text" && (p as { synthetic?: boolean }).synthetic)
+      expect(noticePart).toBeDefined()
+      if (noticePart && noticePart.type === "text") {
+        expect(noticePart.text).toContain("imported from an external session")
+        expect((noticePart as { ignored?: boolean }).ignored).toBe(true)
+      }
+    }),
+  { config: cfg },
+  30_000,
+)
+
+it.instance(
+  "rejects unsupported Claude major version",
+  () =>
+    Effect.gen(function* () {
+      const { dir } = yield* useServerConfig(providerCfg)
+      const { prompt, chat } = yield* boot()
+      yield* withClaudeFixture(dir, claudeInvalidVersion, fixtureUUID)
+
+      const exit = yield* Effect.exit(
+        prompt.command({
+          sessionID: chat.id,
+          command: "resume-claude",
+          arguments: fixtureUUID,
+          agent: "build",
+        }),
+      )
+
+      expect(Exit.isFailure(exit)).toBe(true)
+      if (Exit.isFailure(exit)) {
+        const err = exit.cause
+        const msg = JSON.stringify(err)
+        expect(msg).toContain("Unsupported")
+      }
+    }),
+  { config: cfg },
+  30_000,
+)
+
+it.instance(
+  "rejects unknown UUID with clear error",
+  () =>
+    Effect.gen(function* () {
+      const { dir } = yield* useServerConfig(providerCfg)
+      const { prompt, chat } = yield* boot()
+      const unknownID = "00000000-0000-0000-0000-000000000000"
+      // No fixture file for this UUID
+
+      const exit = yield* Effect.exit(
+        prompt.command({
+          sessionID: chat.id,
+          command: "resume-claude",
+          arguments: unknownID,
+          agent: "build",
+        }),
+      )
+
+      expect(Exit.isFailure(exit)).toBe(true)
+      if (Exit.isFailure(exit)) {
+        const msg = JSON.stringify(exit.cause)
+        expect(msg).toContain("No Claude Code session found")
+      }
+    }),
+  { config: cfg },
+  30_000,
+)
+
+it.instance(
+  "rejects nonempty session with clear error",
+  () =>
+    Effect.gen(function* () {
+      const { dir } = yield* useServerConfig(providerCfg)
+      const { prompt, sessions, chat } = yield* boot()
+      const content = yield* Effect.promise(() => claudeFixture())
+      yield* withClaudeFixture(dir, content, fixtureUUID)
+
+      // Seed a user message so the session is not empty
+      const msg = yield* sessions.updateMessage({
+        id: MessageID.ascending(),
+        role: "user",
+        sessionID: chat.id,
+        agent: "build",
+        model: ref,
+        time: { created: Date.now() },
+      })
+      yield* sessions.updatePart({
+        id: PartID.ascending(),
+        messageID: msg.id,
+        sessionID: chat.id,
+        type: "text",
+        text: "Hello",
+      })
+
+      const exit = yield* Effect.exit(
+        prompt.command({
+          sessionID: chat.id,
+          command: "resume-claude",
+          arguments: fixtureUUID,
+          agent: "build",
+        }),
+      )
+
+      expect(Exit.isFailure(exit)).toBe(true)
+      if (Exit.isFailure(exit)) {
+        const msg = JSON.stringify(exit.cause)
+        expect(msg).toContain("new Kilo session")
+      }
+    }),
+  { config: cfg },
+  30_000,
+)
+
+it.instance(
+  "rejects empty argument when no picker selections exist",
+  () =>
+    Effect.gen(function* () {
+      const { dir } = yield* useServerConfig(providerCfg)
+      const { prompt, chat } = yield* boot()
+
+      const exit = yield* Effect.exit(
+        prompt.command({
+          sessionID: chat.id,
+          command: "resume-claude",
+          arguments: "",
+          agent: "build",
+        }),
+      )
+
+      expect(Exit.isFailure(exit)).toBe(true)
+      if (Exit.isFailure(exit)) {
+        const msg = JSON.stringify(exit.cause)
+        expect(msg).toContain("No session transcripts found")
+      }
+    }),
+  { config: cfg },
+  30_000,
+)
+
+it.instance(
+  "rejects invalid UUID argument",
+  () =>
+    Effect.gen(function* () {
+      const { dir } = yield* useServerConfig(providerCfg)
+      const { prompt, chat } = yield* boot()
+
+      const exit = yield* Effect.exit(
+        prompt.command({
+          sessionID: chat.id,
+          command: "resume-claude",
+          arguments: "not-a-uuid",
+          agent: "build",
+        }),
+      )
+
+      expect(Exit.isFailure(exit)).toBe(true)
+      if (Exit.isFailure(exit)) {
+        const msg = JSON.stringify(exit.cause)
+        expect(msg).toContain("Invalid UUID")
+      }
+    }),
+  { config: cfg },
+  30_000,
+)
+
+it.instance(
+  "imported session writable and queryable through Session.Service",
+  () =>
+    Effect.gen(function* () {
+      const { dir } = yield* useServerConfig(providerCfg)
+      const { prompt, sessions, chat } = yield* boot()
+      const content = yield* Effect.promise(() => claudeFixture())
+      yield* withClaudeFixture(dir, content, fixtureUUID)
+
+      yield* prompt.command({
+        sessionID: chat.id,
+        command: "resume-claude",
+        arguments: fixtureUUID,
+        agent: "build",
+      })
+
+      const msgs = yield* sessions.messages({ sessionID: chat.id })
+      expect(msgs.length).toBeGreaterThanOrEqual(10)
+
+      const parts = msgs.flatMap((msg) => msg.parts)
+      const textParts = parts.filter((p) => p.type === "text")
+      expect(textParts.length).toBeGreaterThan(0)
+
+      const toolParts = parts.filter((p) => p.type === "tool")
+      expect(toolParts.length).toBeGreaterThan(0)
+    }),
+  { config: cfg },
+  30_000,
+)
+
+// ── Codex fixture helpers ────────────────────────────────────────────────
+
+const codexFixture = () =>
+  Bun.file(path.join(__dirname, "fixture/session-resume/codex.jsonl")).text()
+
+const withCodexFixture = (content: string, id: string) =>
+  Effect.acquireRelease(
+    Effect.gen(function* () {
+      const dir = path.join(os.homedir(), ".codex", "sessions")
+      const file = path.join(dir, `rollout-${id}.jsonl`)
+      yield* writeText(file, content)
+      return file
+    }),
+    (file) =>
+      Effect.gen(function* () {
+        fs.rmSync(file, { force: true })
+      }),
+  )
+
+// ── Codex explicit ID import ─────────────────────────────────────────────
+
+it.instance(
+  "explicit Codex ID import produces normal session history",
+  () =>
+    Effect.gen(function* () {
+      const { dir } = yield* useServerConfig(providerCfg)
+      const { prompt, chat } = yield* boot()
+      const content = yield* Effect.promise(() => codexFixture())
+      yield* withCodexFixture(content, fixtureUUID)
+
+      yield* prompt.command({
+        sessionID: chat.id,
+        command: "resume-codex",
+        arguments: fixtureUUID,
+        agent: "build",
+      })
+
+      const msgs = yield* sessionMessages(chat.id)
+      // Codex fixture has 7 user turns + 6 assistant turns + notice
+      expect(msgs.length).toBeGreaterThanOrEqual(8)
+
+      expect(msgs[0].info.role).toBe("user")
+
+      // Last message must be assistant with import notice
+      const last = msgs[msgs.length - 1]
+      expect(last.info.role).toBe("assistant")
+      const text = last.parts.find((p) => p.type === "text")
+      expect(text?.type === "text" && text.text).toContain("imported from an external session")
+    }),
+  { config: cfg },
+  30_000,
+)
+
+it.instance(
+  "imported Codex assistant messages carry complete fields",
+  () =>
+    Effect.gen(function* () {
+      const { dir } = yield* useServerConfig(providerCfg)
+      const { prompt, chat } = yield* boot()
+      const content = yield* Effect.promise(() => codexFixture())
+      yield* withCodexFixture(content, fixtureUUID)
+
+      yield* prompt.command({
+        sessionID: chat.id,
+        command: "resume-codex",
+        arguments: fixtureUUID,
+        agent: "build",
+      })
+
+      const msgs = yield* sessionMessages(chat.id)
+
+      for (const msg of msgs) {
+        if (msg.info.role === "assistant") {
+          expect(msg.info.providerID).toBeString()
+          expect(msg.info.modelID).toBeString()
+          expect(msg.info.finish).toBe("stop")
+          expect(msg.info.agent).toBe("build")
+        }
+      }
+    }),
+  { config: cfg },
+  30_000,
+)
+
+it.instance(
+  "imported Codex session contains tool states with completed and error status",
+  () =>
+    Effect.gen(function* () {
+      const { dir } = yield* useServerConfig(providerCfg)
+      const { prompt, chat } = yield* boot()
+      const content = yield* Effect.promise(() => codexFixture())
+      yield* withCodexFixture(content, fixtureUUID)
+
+      yield* prompt.command({
+        sessionID: chat.id,
+        command: "resume-codex",
+        arguments: fixtureUUID,
+        agent: "build",
+      })
+
+      const msgs = yield* sessionMessages(chat.id)
+
+      const tools = msgs.flatMap((msg) => msg.parts.filter((p) => p.type === "tool"))
+      expect(tools.length).toBeGreaterThanOrEqual(2)
+
+      const completed = tools.filter(
+        (t) => (t as { state: { status: string } }).state.status === "completed",
+      )
+      expect(completed.length).toBeGreaterThanOrEqual(1)
+    }),
+  { config: cfg },
+  30_000,
+)
+
+// ── Picker / no-ID import ─────────────────────────────────────────────────
+
+const tmpRoots = Effect.fn("test.tmpRoots")(function* () {
+  const test = yield* TestInstance
+  const claude = path.join(test.directory, "tmp-claude-projects")
+  const codex = path.join(test.directory, "tmp-codex-sessions")
+  return { claude, codex }
+})
+
+const withClaudeFixtureAt = (root: string, cwd: string, content: string, id: string) =>
+  Effect.acquireRelease(
+    Effect.gen(function* () {
+      const dir = path.join(root, claudeSlug(cwd))
+      const file = path.join(dir, `${id}.jsonl`)
+      yield* writeText(file, content)
+      return file
+    }),
+    (file) =>
+      Effect.gen(function* () {
+        fs.rmSync(path.dirname(file), { recursive: true, force: true })
+      }),
+  )
+
+const codexFixtureForCwdAt = (cwd: string) =>
+  Effect.gen(function* () {
+    const raw = yield* Effect.promise(() => codexFixture())
+    // Escape backslashes so the JSON stays valid on Windows paths.
+    const escaped = cwd.replace(/\\/g, "\\\\")
+    return raw.replace(/"cwd":"[^"]*"/, `"cwd":"${escaped}"`)
+  })
+
+const withCodexFixtureAt = (root: string, content: string, id: string) =>
+  Effect.acquireRelease(
+    Effect.gen(function* () {
+      const file = path.join(root, `rollout-${id}.jsonl`)
+      yield* writeText(file, content)
+      return file
+    }),
+    (file) =>
+      Effect.gen(function* () {
+        fs.rmSync(file, { force: true })
+      }),
+  )
+
+itPicker.instance(
+  "Claude picker import discovers and imports the most recent session",
+  () =>
+    Effect.gen(function* () {
+      const { dir } = yield* useServerConfig(providerCfg)
+      const roots = yield* tmpRoots()
+      const { prompt, chat } = yield* boot()
+      const content = yield* Effect.promise(() => claudeFixture())
+
+      yield* withClaudeFixtureAt(roots.claude, dir, content, fixtureUUID)
+
+      yield* prompt.command({
+        sessionID: chat.id,
+        command: "resume-claude",
+        arguments: "",
+        agent: "build",
+      }).pipe(
+        Effect.provideService(SessionResume.ResumeRoots, { claude: roots.claude }),
+      )
+
+      const msgs = yield* sessionMessages(chat.id)
+      expect(msgs.length).toBeGreaterThanOrEqual(10)
+
+      expect(msgs[0].info.role).toBe("user")
+      const last = msgs[msgs.length - 1]
+      expect(last.info.role).toBe("assistant")
+      const text = last.parts.find((p) => p.type === "text")
+      expect(text?.type === "text" && text.text).toContain("imported from an external session")
+    }),
+  { config: cfg },
+  30_000,
+)
+
+itPicker.instance(
+  "Codex picker import discovers and imports the most recent session",
+  () =>
+    Effect.gen(function* () {
+      const { dir } = yield* useServerConfig(providerCfg)
+      const roots = yield* tmpRoots()
+      const { prompt, chat } = yield* boot()
+      const content = yield* codexFixtureForCwdAt(dir)
+
+      yield* withCodexFixtureAt(roots.codex, content, fixtureUUID)
+
+      yield* prompt.command({
+        sessionID: chat.id,
+        command: "resume-codex",
+        arguments: "",
+        agent: "build",
+      }).pipe(
+        Effect.provideService(SessionResume.ResumeRoots, { codex: roots.codex }),
+      )
+
+      const msgs = yield* sessionMessages(chat.id)
+      expect(msgs.length).toBeGreaterThanOrEqual(8)
+
+      expect(msgs[0].info.role).toBe("user")
+      const last = msgs[msgs.length - 1]
+      expect(last.info.role).toBe("assistant")
+      const text = last.parts.find((p) => p.type === "text")
+      expect(text?.type === "text" && text.text).toContain("imported from an external session")
+    }),
+  { config: cfg },
+  30_000,
+)
+
+// ── Unreadable directory case ─────────────────────────────────────────────
+
+it.instance(
+  "rejects when a session ID resolves to a directory instead of a file",
+  () =>
+    Effect.gen(function* () {
+      const { dir } = yield* useServerConfig(providerCfg)
+      const test = yield* TestInstance
+      const { prompt, chat } = yield* boot()
+
+      // Use a temp root instead of real home directory
+      const root = path.join(test.directory, "tmp-claude-projects")
+      const file = path.join(root, claudeSlug(dir), `${fixtureUUID}.jsonl`)
+
+      // acquireRelease: create a directory at the expected file path,
+      // clean up on scope exit even if assertion fails
+      yield* Effect.acquireRelease(
+        Effect.sync(() => {
+          fs.mkdirSync(file, { recursive: true })
+        }),
+        () => Effect.sync(() => {
+          fs.rmSync(path.dirname(file), { recursive: true, force: true })
+        }),
+      )
+
+      const exit = yield* Effect.exit(
+        prompt.command({
+          sessionID: chat.id,
+          command: "resume-claude",
+          arguments: fixtureUUID,
+          agent: "build",
+        }).pipe(
+          Effect.provideService(SessionResume.ResumeRoots, { claude: root }),
+        ),
+      )
+
+      expect(Exit.isFailure(exit)).toBe(true)
+      if (Exit.isFailure(exit)) {
+        const msg = JSON.stringify(exit.cause)
+        expect(msg).toContain("Unreadable Claude transcript")
+      }
+
+      // Assert no messages were written
+      const msgs = yield* sessionMessages(chat.id)
+      expect(msgs.length).toBe(0)
+    }),
+  { config: cfg },
+  30_000,
+)
+
+// ── Failure state asserts ─────────────────────────────────────────────────
+
+it.instance(
+  "unknown UUID failure writes no session messages",
+  () =>
+    Effect.gen(function* () {
+      const { dir } = yield* useServerConfig(providerCfg)
+      const { prompt, chat } = yield* boot()
+      const unknownID = "00000000-0000-0000-0000-000000000000"
+
+      yield* Effect.exit(
+        prompt.command({
+          sessionID: chat.id,
+          command: "resume-claude",
+          arguments: unknownID,
+          agent: "build",
+        }),
+      )
+
+      const msgs = yield* sessionMessages(chat.id)
+      expect(msgs.length).toBe(0)
+    }),
+  { config: cfg },
+  30_000,
+)
+
+it.instance(
+  "unsupported version failure writes no session messages",
+  () =>
+    Effect.gen(function* () {
+      const { dir } = yield* useServerConfig(providerCfg)
+      const { prompt, chat } = yield* boot()
+      yield* withClaudeFixture(dir, claudeInvalidVersion, fixtureUUID)
+
+      yield* Effect.exit(
+        prompt.command({
+          sessionID: chat.id,
+          command: "resume-claude",
+          arguments: fixtureUUID,
+          agent: "build",
+        }),
+      )
+
+      const msgs = yield* sessionMessages(chat.id)
+      expect(msgs.length).toBe(0)
+    }),
+  { config: cfg },
+  30_000,
+)
+
+it.instance(
+  "nonempty session failure writes no additional messages",
+  () =>
+    Effect.gen(function* () {
+      const { dir } = yield* useServerConfig(providerCfg)
+      const { prompt, sessions, chat } = yield* boot()
+      const content = yield* Effect.promise(() => claudeFixture())
+      yield* withClaudeFixture(dir, content, fixtureUUID)
+
+      // Mark session as nonempty
+      const msg = yield* sessions.updateMessage({
+        id: MessageID.ascending(),
+        role: "user",
+        sessionID: chat.id,
+        agent: "build",
+        model: ref,
+        time: { created: Date.now() },
+      })
+
+      yield* Effect.exit(
+        prompt.command({
+          sessionID: chat.id,
+          command: "resume-claude",
+          arguments: fixtureUUID,
+          agent: "build",
+        }),
+      )
+
+      // The single user message from seeding must still be the only message
+      const msgs = yield* sessions.messages({ sessionID: chat.id })
+      expect(msgs.length).toBe(1)
+      expect(msgs[0].info.id).toBe(msg.id)
+    }),
+  { config: cfg },
+  30_000,
+)
+
+// ── Tool schema decoding ──────────────────────────────────────────────────
+
+it.instance(
+  "decodes imported tool parts through SessionV1.ToolPart schema",
+  () =>
+    Effect.gen(function* () {
+      const { dir } = yield* useServerConfig(providerCfg)
+      const { prompt, chat } = yield* boot()
+      const content = yield* Effect.promise(() => claudeFixture())
+      yield* withClaudeFixture(dir, content, fixtureUUID)
+
+      yield* prompt.command({
+        sessionID: chat.id,
+        command: "resume-claude",
+        arguments: fixtureUUID,
+        agent: "build",
+      })
+
+      const msgs = yield* sessionMessages(chat.id)
+
+      for (const msg of msgs) {
+        for (const part of msg.parts) {
+          if (part.type === "tool") {
+            // Must decode without error
+            const decoded = Schema.decodeUnknownSync(SessionV1.ToolPart)(part)
+            expect(decoded.type).toBe("tool")
+            expect(typeof decoded.callID).toBe("string")
+            expect(typeof decoded.tool).toBe("string")
+            expect(decoded.state).toBeDefined()
+          }
+        }
+      }
+    }),
+  { config: cfg },
+  30_000,
+)
+
+it.instance(
+  "decodes imported Codex tool parts through SessionV1.ToolPart schema",
+  () =>
+    Effect.gen(function* () {
+      const { dir } = yield* useServerConfig(providerCfg)
+      const { prompt, chat } = yield* boot()
+      const content = yield* Effect.promise(() => codexFixture())
+      yield* withCodexFixture(content, fixtureUUID)
+
+      yield* prompt.command({
+        sessionID: chat.id,
+        command: "resume-codex",
+        arguments: fixtureUUID,
+        agent: "build",
+      })
+
+      const msgs = yield* sessionMessages(chat.id)
+
+      for (const msg of msgs) {
+        for (const part of msg.parts) {
+          if (part.type === "tool") {
+            const decoded = Schema.decodeUnknownSync(SessionV1.ToolPart)(part)
+            expect(decoded.type).toBe("tool")
+            expect(typeof decoded.callID).toBe("string")
+            expect(typeof decoded.tool).toBe("string")
+            expect(decoded.state).toBeDefined()
+          }
+        }
+      }
+    }),
+  { config: cfg },
+  30_000,
+)
diff --git a/packages/opencode/test/kilocode/session-resume.test.ts b/packages/opencode/test/kilocode/session-resume.test.ts
new file mode 100644
index 00000000000..a9fa07a7dbe
--- /dev/null
+++ b/packages/opencode/test/kilocode/session-resume.test.ts
@@ -0,0 +1,980 @@
+import { describe, expect, test } from "bun:test"
+import fs from "node:fs"
+import os from "node:os"
+import path from "node:path"
+import { SessionResume } from "../../src/kilocode/session-resume"
+
+// ── UUID validation ───────────────────────────────────────────────────
+
+describe("SessionResume.isUUID", () => {
+  test("accepts valid UUID v4", () => {
+    expect(SessionResume.isUUID("550e8400-e29b-41d4-a716-446655440000")).toBe(true)
+  })
+
+  test("rejects non-UUID string", () => {
+    expect(SessionResume.isUUID("not-a-uuid")).toBe(false)
+    expect(SessionResume.isUUID("")).toBe(false)
+    expect(SessionResume.isUUID("g1234567-1234-1234-1234-1234567890ab")).toBe(false)
+  })
+})
+
+describe("SessionResume.validateUUID", () => {
+  test("does not throw for valid UUID", () => {
+    expect(() => SessionResume.validateUUID("550e8400-e29b-41d4-a716-446655440000")).not.toThrow()
+  })
+
+  test("throws for invalid UUID", () => {
+    expect(() => SessionResume.validateUUID("bad")).toThrow(SessionResume.ParseError)
+  })
+})
+
+// ── Detection ────────────────────────────────────────────────────────
+
+describe("SessionResume.detect", () => {
+  test("detects Claude format from real top-level envelope", () => {
+    const line = {
+      type: "user",
+      version: "2.42.0",
+      isSidechain: false,
+      message: { id: "msg_001", role: "user", content: [{ type: "text", text: "hello" }] },
+    }
+    expect(SessionResume.detect(line)).toBe("claude")
+  })
+
+  test("detects Claude format from assistant with tool_use", () => {
+    const line = {
+      type: "assistant",
+      version: "2.42.0",
+      isSidechain: false,
+      message: {
+        id: "msg_002",
+        role: "assistant",
+        content: [{ type: "tool_use", id: "toolu_01", name: "read", input: {} }],
+      },
+    }
+    expect(SessionResume.detect(line)).toBe("claude")
+  })
+
+  test("detects Codex format from session_meta", () => {
+    const line = { type: "session_meta", payload: { cli_version: "0.8.0", cwd: "/test" } }
+    expect(SessionResume.detect(line)).toBe("codex")
+  })
+
+  test("detects Codex format from response_item", () => {
+    const line = {
+      type: "response_item",
+      payload: {
+        id: "item_001",
+        type: "message",
+        role: "user",
+        content: [{ type: "input_text", text: "hello" }],
+      },
+    }
+    expect(SessionResume.detect(line)).toBe("codex")
+  })
+
+  test("returns undefined for non-message objects", () => {
+    expect(SessionResume.detect(null)).toBeUndefined()
+    expect(SessionResume.detect("string")).toBeUndefined()
+    expect(SessionResume.detect({})).toBeUndefined()
+    expect(SessionResume.detect([])).toBeUndefined()
+  })
+})
+
+// ── Claude parsing ───────────────────────────────────────────────────
+
+describe("Claude parseLines", () => {
+  test("parses simple user+assistant text exchange with real envelopes", () => {
+    const text = [
+      '{"type":"user","version":"2.42.0","isSidechain":false,"message":{"id":"msg_001","role":"user","content":[{"type":"text","text":"Hello"}]}}',
+      '{"type":"assistant","version":"2.42.0","isSidechain":false,"message":{"id":"msg_002","role":"assistant","content":[{"type":"text","text":"Hi there!"}]}}',
+    ].join("\n")
+
+    const result = SessionResume.parseLines(text)
+    expect(result.format).toBe("claude")
+    expect(result.version).toBe(2)
+    expect(result.steps).toHaveLength(2)
+    expect(result.steps[0]).toEqual({
+      role: "user",
+      parts: [{ type: "text", text: "Hello" }],
+    })
+    expect(result.steps[1]).toEqual({
+      role: "assistant",
+      parts: [{ type: "text", text: "Hi there!" }],
+    })
+  })
+
+  test("accepts string user content and ignores transcript metadata", () => {
+    const text = [
+      '{"type":"permission-mode","sessionId":"session"}',
+      '{"type":"user","version":"2.42.0","message":{"role":"user","content":"Hello"}}',
+      '{"type":"assistant","version":"2.42.0","message":{"role":"assistant","content":[{"type":"text","text":"Hi"}]}}',
+    ].join("\n")
+
+    expect(SessionResume.parseLines(text).steps).toEqual([
+      { role: "user", parts: [{ type: "text", text: "Hello" }] },
+      { role: "assistant", parts: [{ type: "text", text: "Hi" }] },
+    ])
+  })
+
+  test("keeps a real user turn beside paired tool results", () => {
+    const text = [
+      '{"type":"user","version":"2.42.0","message":{"role":"user","content":[{"type":"text","text":"Start"}]}}',
+      '{"type":"assistant","version":"2.42.0","message":{"role":"assistant","content":[{"type":"tool_use","id":"tool","name":"read","input":{}}]}}',
+      '{"type":"user","version":"2.42.0","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"tool","content":"done"},{"type":"text","text":"Continue"}]}}',
+    ].join("\n")
+
+    expect(SessionResume.parseLines(text).steps.map((step) => step.role)).toEqual(["user", "assistant", "user"])
+    expect(SessionResume.parseLines(text).steps[2]?.parts).toEqual([{ type: "text", text: "Continue" }])
+  })
+
+  test("keeps a partially paired tool step before a mixed later user turn", () => {
+    const text = [
+      '{"type":"user","version":"2.42.0","message":{"role":"user","content":"Start"}}',
+      '{"type":"assistant","version":"2.42.0","message":{"role":"assistant","content":[{"type":"tool_use","id":"first","name":"read","input":{}},{"type":"tool_use","id":"second","name":"edit","input":{}}]}}',
+      '{"type":"user","version":"2.42.0","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"first","content":"done"},{"type":"text","text":"Also say hi"}]}}',
+    ].join("\n")
+
+    const steps = SessionResume.parseLines(text).steps
+    expect(steps.map((step) => step.role)).toEqual(["user", "assistant", "user"])
+    expect(steps[1]?.parts.map((part) => part.type)).toEqual(["tool_call", "tool_call", "tool_result", "error"])
+    expect(steps[2]?.parts).toEqual([{ type: "text", text: "Also say hi" }])
+  })
+
+  test("normalizes object tool results", () => {
+    const claude = [
+      '{"type":"user","version":"2.42.0","message":{"role":"user","content":[{"type":"text","text":"Start"}]}}',
+      '{"type":"assistant","version":"2.42.0","message":{"role":"assistant","content":[{"type":"tool_use","id":"tool","name":"read","input":{}}]}}',
+      '{"type":"user","version":"2.42.0","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"tool","content":{"value":1}}]}}',
+    ].join("\n")
+    const claudeTool = SessionResume.parseLines(claude).steps[1]?.parts.find((part) => part.type === "tool_result")
+    expect(claudeTool).toMatchObject({ content: '{"value":1}' })
+  })
+
+  test("reads version from real Claude envelope", () => {
+    const text = [
+      '{"type":"user","version":"2.42.0","isSidechain":false,"message":{"id":"msg_001","role":"user","content":[{"type":"text","text":"Hello"}]}}',
+      '{"type":"assistant","version":"2.42.0","isSidechain":false,"message":{"id":"msg_002","role":"assistant","content":[{"type":"text","text":"Hi"}]}}',
+    ].join("\n")
+
+    const result = SessionResume.parseLines(text)
+    expect(result.version).toBe(2)
+  })
+
+  test("rejects unsupported Claude major version", () => {
+    const text = [
+      '{"type":"user","version":"3.0.0","isSidechain":false,"message":{"id":"msg_001","role":"user","content":[{"type":"text","text":"Hello"}]}}',
+    ].join("\n")
+
+    expect(() => SessionResume.parseLines(text)).toThrow(SessionResume.ParseError)
+  })
+
+  test("rejects Claude records without version field", () => {
+    const text = [
+      '{"type":"user","isSidechain":false,"message":{"id":"msg_001","role":"user","content":[{"type":"text","text":"Hello"}]}}',
+    ].join("\n")
+
+    expect(() => SessionResume.parseLines(text)).toThrow("missing version")
+  })
+
+  test("pairs tool_use with tool_result", () => {
+    const text = [
+      '{"type":"user","version":"2.42.0","isSidechain":false,"message":{"id":"msg_001","role":"user","content":[{"type":"text","text":"Read file"}]}}',
+      '{"type":"assistant","version":"2.42.0","isSidechain":false,"message":{"id":"msg_002","role":"assistant","content":[{"type":"text","text":"Reading..."},{"type":"tool_use","id":"toolu_01","name":"read","input":{"file":"foo.ts"}}]}}',
+      '{"type":"user","version":"2.42.0","isSidechain":false,"message":{"id":"msg_003","role":"user","content":[{"type":"tool_result","tool_use_id":"toolu_01","content":"file contents"}]}}',
+      '{"type":"assistant","version":"2.42.0","isSidechain":false,"message":{"id":"msg_004","role":"assistant","content":[{"type":"text","text":"Done."}]}}',
+    ].join("\n")
+
+    const result = SessionResume.parseLines(text)
+    expect(result.steps).toHaveLength(3)
+
+    expect(result.steps[0].role).toBe("user")
+    expect(result.steps[0].parts).toEqual([{ type: "text", text: "Read file" }])
+
+    expect(result.steps[1].role).toBe("assistant")
+    const tc = result.steps[1].parts.find((p): p is SessionResume.ToolCall => p.type === "tool_call")
+    const tr = result.steps[1].parts.find((p): p is SessionResume.ToolResult => p.type === "tool_result")
+    expect(tc).toBeDefined()
+    expect(tc!.id).toBe("toolu_01")
+    expect(tc!.name).toBe("read")
+    expect(tr).toBeDefined()
+    expect(tr!.callID).toBe("toolu_01")
+    expect(tr!.content).toBe("file contents")
+
+    expect(result.steps[2].role).toBe("assistant")
+    expect(result.steps[2].parts).toEqual([{ type: "text", text: "Done." }])
+  })
+
+  test("pairs multiple tool calls with results in one round", () => {
+    const text = [
+      '{"type":"user","version":"2.42.0","isSidechain":false,"message":{"id":"msg_001","role":"user","content":[{"type":"text","text":"Do two things"}]}}',
+      '{"type":"assistant","version":"2.42.0","isSidechain":false,"message":{"id":"msg_002","role":"assistant","content":[{"type":"tool_use","id":"call_a","name":"read","input":{}},{"type":"tool_use","id":"call_b","name":"edit","input":{}}]}}',
+      '{"type":"user","version":"2.42.0","isSidechain":false,"message":{"id":"msg_003","role":"user","content":[{"type":"tool_result","tool_use_id":"call_a","content":"result A"},{"type":"tool_result","tool_use_id":"call_b","content":"result B"}]}}',
+      '{"type":"assistant","version":"2.42.0","isSidechain":false,"message":{"id":"msg_004","role":"assistant","content":[{"type":"text","text":"Both done."}]}}',
+    ].join("\n")
+
+    const result = SessionResume.parseLines(text)
+    expect(result.steps).toHaveLength(3)
+
+    const mid = result.steps[1]
+    expect(mid.role).toBe("assistant")
+    const calls = mid.parts.filter((p): p is SessionResume.ToolCall => p.type === "tool_call")
+    const results = mid.parts.filter((p): p is SessionResume.ToolResult => p.type === "tool_result")
+    expect(calls).toHaveLength(2)
+    expect(results).toHaveLength(2)
+    expect(calls.map((c) => c.id).sort()).toEqual(["call_a", "call_b"])
+    expect(results.map((r) => r.callID).sort()).toEqual(["call_a", "call_b"])
+  })
+
+  test("merges consecutive assistant messages into one pending step", () => {
+    const text = [
+      '{"type":"user","version":"2.42.0","isSidechain":false,"message":{"id":"msg_001","role":"user","content":[{"type":"text","text":"Go"}]}}',
+      '{"type":"assistant","version":"2.42.0","isSidechain":false,"message":{"id":"msg_002","role":"assistant","content":[{"type":"tool_use","id":"a","name":"read","input":{}}]}}',
+      '{"type":"assistant","version":"2.42.0","isSidechain":false,"message":{"id":"msg_003","role":"assistant","content":[{"type":"tool_use","id":"b","name":"edit","input":{}}]}}',
+      '{"type":"user","version":"2.42.0","isSidechain":false,"message":{"id":"msg_004","role":"user","content":[{"type":"tool_result","tool_use_id":"a","content":"ra"},{"type":"tool_result","tool_use_id":"b","content":"rb"}]}}',
+      '{"type":"assistant","version":"2.42.0","isSidechain":false,"message":{"id":"msg_005","role":"assistant","content":[{"type":"text","text":"Done."}]}}',
+    ].join("\n")
+
+    const result = SessionResume.parseLines(text)
+    expect(result.steps).toHaveLength(3)
+
+    const mid = result.steps[1]
+    expect(mid.role).toBe("assistant")
+    const calls = mid.parts.filter((p): p is SessionResume.ToolCall => p.type === "tool_call")
+    const results = mid.parts.filter((p): p is SessionResume.ToolResult => p.type === "tool_result")
+    expect(calls).toHaveLength(2)
+    expect(results).toHaveLength(2)
+    expect(calls.map((c) => c.id).sort()).toEqual(["a", "b"])
+    expect(results.map((r) => r.callID).sort()).toEqual(["a", "b"])
+  })
+
+  test("excludes sidechain records from parsed history", () => {
+    const text = [
+      '{"type":"user","version":"2.42.0","isSidechain":false,"message":{"id":"msg_001","role":"user","content":[{"type":"text","text":"Hello"}]}}',
+      '{"type":"user","version":"2.42.0","isSidechain":true,"message":{"id":"side_001","role":"user","content":[{"type":"text","text":"Sidechain"}]}}',
+      '{"type":"assistant","version":"2.42.0","isSidechain":false,"message":{"id":"msg_002","role":"assistant","content":[{"type":"text","text":"Hi"}]}}',
+    ].join("\n")
+
+    const result = SessionResume.parseLines(text)
+    expect(result.steps).toHaveLength(2)
+    expect(result.steps[0].role).toBe("user")
+    expect(result.steps[0].parts).toEqual([{ type: "text", text: "Hello" }])
+    expect(result.steps[1].role).toBe("assistant")
+    expect(result.steps[1].parts).toEqual([{ type: "text", text: "Hi" }])
+  })
+
+  test("skips known metadata record types", () => {
+    const text = [
+      '{"type":"user","version":"2.42.0","isSidechain":false,"message":{"id":"msg_001","role":"user","content":[{"type":"text","text":"Hello"}]}}',
+      '{"type":"ai-title","version":"2.42.0","isSidechain":true,"message":{"id":"title_001","role":"assistant","content":[{"type":"text","text":"Session title"}]}}',
+      '{"type":"assistant","version":"2.42.0","isSidechain":false,"message":{"id":"msg_002","role":"assistant","content":[{"type":"text","text":"Hi"}]}}',
+    ].join("\n")
+
+    const result = SessionResume.parseLines(text)
+    expect(result.steps).toHaveLength(2)
+  })
+
+  test("handles unpaired tool call in final step", () => {
+    const text = [
+      '{"type":"user","version":"2.42.0","isSidechain":false,"message":{"id":"msg_001","role":"user","content":[{"type":"text","text":"Run"}]}}',
+      '{"type":"assistant","version":"2.42.0","isSidechain":false,"message":{"id":"msg_002","role":"assistant","content":[{"type":"tool_use","id":"orphan_1","name":"read","input":{}}]}}',
+      '{"type":"user","version":"2.42.0","isSidechain":false,"message":{"id":"msg_003","role":"user","content":[{"type":"text","text":"New topic"}]}}',
+    ].join("\n")
+
+    const result = SessionResume.parseLines(text)
+    expect(result.steps).toHaveLength(3)
+
+    const mid = result.steps[1]
+    expect(mid.role).toBe("assistant")
+    const errors = mid.parts.filter((p): p is SessionResume.ErrorPart => p.type === "error")
+    expect(errors).toHaveLength(1)
+    expect(errors[0].message).toContain("Unpaired tool call")
+    expect(errors[0].message).toContain("orphan_1")
+  })
+
+  test("handles repeated tool_use IDs across different rounds", () => {
+    const text = [
+      '{"type":"user","version":"2.42.0","isSidechain":false,"message":{"id":"msg_001","role":"user","content":[{"type":"text","text":"Read twice"}]}}',
+      '{"type":"assistant","version":"2.42.0","isSidechain":false,"message":{"id":"msg_002","role":"assistant","content":[{"type":"tool_use","id":"toolu_01","name":"read","input":{"file":"a.ts"}}]}}',
+      '{"type":"user","version":"2.42.0","isSidechain":false,"message":{"id":"msg_003","role":"user","content":[{"type":"tool_result","tool_use_id":"toolu_01","content":"content a"}]}}',
+      '{"type":"assistant","version":"2.42.0","isSidechain":false,"message":{"id":"msg_004","role":"assistant","content":[{"type":"text","text":"First read done."}]}}',
+      '{"type":"user","version":"2.42.0","isSidechain":false,"message":{"id":"msg_005","role":"user","content":[{"type":"text","text":"Read again"}]}}',
+      '{"type":"assistant","version":"2.42.0","isSidechain":false,"message":{"id":"msg_006","role":"assistant","content":[{"type":"tool_use","id":"toolu_01","name":"read","input":{"file":"b.ts"}}]}}',
+      '{"type":"user","version":"2.42.0","isSidechain":false,"message":{"id":"msg_007","role":"user","content":[{"type":"tool_result","tool_use_id":"toolu_01","content":"content b"}]}}',
+      '{"type":"assistant","version":"2.42.0","isSidechain":false,"message":{"id":"msg_008","role":"assistant","content":[{"type":"text","text":"Second read done."}]}}',
+    ].join("\n")
+
+    const result = SessionResume.parseLines(text)
+    const toolSteps = result.steps.filter(
+      (s) => s.role === "assistant" && s.parts.some((p) => p.type === "tool_call"),
+    )
+    expect(toolSteps).toHaveLength(2)
+
+    for (const step of toolSteps) {
+      const tr = step.parts.find((p): p is SessionResume.ToolResult => p.type === "tool_result")
+      expect(tr).toBeDefined()
+      expect(tr!.callID).toBe("toolu_01")
+    }
+  })
+
+  test("parses reasoning/thinking blocks from real envelope", () => {
+    const text = [
+      '{"type":"user","version":"2.42.0","isSidechain":false,"message":{"id":"msg_001","role":"user","content":[{"type":"text","text":"Q"}]}}',
+      '{"type":"assistant","version":"2.42.0","isSidechain":false,"message":{"id":"msg_002","role":"assistant","content":[{"type":"thinking","thinking":"Let me think...","signature":"sig_test"},{"type":"text","text":"Answer"}]}}',
+    ].join("\n")
+
+    const result = SessionResume.parseLines(text)
+    const assistant = result.steps[1]
+    expect(assistant.role).toBe("assistant")
+    expect(assistant.parts).toHaveLength(2)
+    expect(assistant.parts[0]).toEqual({ type: "reasoning", text: "Let me think..." })
+    expect(assistant.parts[1]).toEqual({ type: "text", text: "Answer" })
+  })
+
+  test("handles redacted_thinking as unsupported", () => {
+    const text = [
+      '{"type":"user","version":"2.42.0","isSidechain":false,"message":{"id":"msg_001","role":"user","content":[{"type":"text","text":"Test"}]}}',
+      '{"type":"assistant","version":"2.42.0","isSidechain":false,"message":{"id":"msg_002","role":"assistant","content":[{"type":"redacted_thinking","data":"encrypted"}]}}',
+    ].join("\n")
+
+    const result = SessionResume.parseLines(text)
+    expect(result.unsupported).toBe(1)
+
+    const assistant = result.steps[1]
+    const unsupportedParts = assistant.parts.filter(
+      (p): p is SessionResume.Unsupported => p.type === "unsupported",
+    )
+    expect(unsupportedParts).toHaveLength(1)
+    expect(unsupportedParts[0].reason).toBe("encrypted reasoning block")
+  })
+
+  test("handles unknown content types as unsupported", () => {
+    const text = [
+      '{"type":"user","version":"2.42.0","isSidechain":false,"message":{"id":"msg_001","role":"user","content":[{"type":"text","text":"Test"}]}}',
+      '{"type":"assistant","version":"2.42.0","isSidechain":false,"message":{"id":"msg_002","role":"assistant","content":[{"type":"custom_block","data":"unknown"}]}}',
+    ].join("\n")
+
+    const result = SessionResume.parseLines(text)
+    expect(result.unsupported).toBe(1)
+
+    const assistant = result.steps[1]
+    const unsupportedParts = assistant.parts.filter(
+      (p): p is SessionResume.Unsupported => p.type === "unsupported",
+    )
+    expect(unsupportedParts).toHaveLength(1)
+    expect(unsupportedParts[0].reason).toContain("unknown content type")
+    expect(unsupportedParts[0].reason).toContain("custom_block")
+  })
+
+  test("counts server_tool_result as unsupported in tool-result message", () => {
+    const text = [
+      '{"type":"user","version":"2.42.0","isSidechain":false,"message":{"id":"msg_001","role":"user","content":[{"type":"text","text":"Go"}]}}',
+      '{"type":"assistant","version":"2.42.0","isSidechain":false,"message":{"id":"msg_002","role":"assistant","content":[{"type":"tool_use","id":"toolu_01","name":"read","input":{}}]}}',
+      '{"type":"user","version":"2.42.0","isSidechain":false,"message":{"id":"msg_003","role":"user","content":[{"type":"tool_result","tool_use_id":"toolu_01","content":"ok"},{"type":"server_tool_result","tool_use_id":"toolu_99","content":"raw"}]}}',
+    ].join("\n")
+
+    const result = SessionResume.parseLines(text)
+    expect(result.unsupported).toBe(1)
+
+    const mid = result.steps[1]
+    expect(mid.role).toBe("assistant")
+    const unsupportedParts = mid.parts.filter(
+      (p): p is SessionResume.Unsupported => p.type === "unsupported",
+    )
+    expect(unsupportedParts).toHaveLength(1)
+    expect(unsupportedParts[0].reason).toBe("server_tool_result block")
+  })
+
+  test("rejects empty input", () => {
+    expect(() => SessionResume.parseLines("")).toThrow(SessionResume.ParseError)
+    expect(() => SessionResume.parseLines("   \n  ")).toThrow(SessionResume.ParseError)
+  })
+
+  test("rejects malformed JSON", () => {
+    expect(() =>
+      SessionResume.parseLines(
+        '{"type":"user","version":"2.42.0","isSidechain":false,"message":{"id":"msg_001","role":"user","content":[{"type":"text","text":"hi"}]}}\n{broken',
+      ),
+    ).toThrow(SessionResume.ParseError)
+  })
+
+  test("rejects a malformed JSON Lines file without returning partial history", async () => {
+    const directory = fs.mkdtempSync(path.join(os.tmpdir(), "resume-jsonl-"))
+    try {
+      const file = path.join(directory, "transcript.jsonl")
+      fs.writeFileSync(
+        file,
+        [
+          '{"type":"user","version":"2.42.0","message":{"role":"user","content":"Start"}}',
+          "invalid-json",
+          '{"type":"assistant","version":"2.42.0","message":{"role":"assistant","content":[{"type":"text","text":"Done"}]}}',
+        ].join("\n"),
+      )
+
+      await expect(SessionResume.parse(file)).rejects.toThrow("Line 2: invalid JSON")
+    } finally {
+      fs.rmSync(directory, { recursive: true, force: true })
+    }
+  })
+})
+
+// ── Codex parsing ────────────────────────────────────────────────────
+
+describe("Codex parseLines", () => {
+  test("parses simple user+assistant text exchange with real envelopes", () => {
+    const text = [
+      '{"type":"session_meta","payload":{"cli_version":"0.8.0","cwd":"/test"}}',
+      '{"type":"response_item","payload":{"id":"item_001","type":"message","role":"user","content":[{"type":"input_text","text":"Hello"}]}}',
+      '{"type":"response_item","payload":{"id":"item_002","type":"message","role":"assistant","content":[{"type":"output_text","text":"Hi there!"}]}}',
+    ].join("\n")
+
+    const result = SessionResume.parseLines(text)
+    expect(result.format).toBe("codex")
+    expect(result.version).toBe(0)
+    expect(result.steps).toHaveLength(2)
+    expect(result.steps[0]).toEqual({
+      role: "user",
+      parts: [{ type: "text", text: "Hello" }],
+    })
+    expect(result.steps[1]).toEqual({
+      role: "assistant",
+      parts: [{ type: "text", text: "Hi there!" }],
+    })
+  })
+
+  test("reads version from session_meta payload", () => {
+    const text = [
+      '{"type":"session_meta","payload":{"cli_version":"0.8.0","cwd":"/test"}}',
+      '{"type":"response_item","payload":{"id":"item_001","type":"message","role":"user","content":[{"type":"input_text","text":"Hello"}]}}',
+      '{"type":"response_item","payload":{"id":"item_002","type":"message","role":"assistant","content":[{"type":"output_text","text":"Hi"}]}}',
+    ].join("\n")
+
+    const result = SessionResume.parseLines(text)
+    expect(result.version).toBe(0)
+  })
+
+  test("rejects Codex file without session_meta", () => {
+    const text = [
+      '{"type":"response_item","payload":{"id":"item_001","type":"message","role":"user","content":[{"type":"input_text","text":"Hello"}]}}',
+    ].join("\n")
+
+    expect(() => SessionResume.parseLines(text)).toThrow(SessionResume.ParseError)
+  })
+
+  test("rejects unsupported Codex major version", () => {
+    const text = [
+      '{"type":"session_meta","payload":{"cli_version":"1.0.0","cwd":"/test"}}',
+      '{"type":"response_item","payload":{"id":"item_001","type":"message","role":"user","content":[{"type":"input_text","text":"Hello"}]}}',
+    ].join("\n")
+
+    expect(() => SessionResume.parseLines(text)).toThrow(SessionResume.ParseError)
+  })
+
+  test("starts a new assistant step after a completed function call", () => {
+    const text = [
+      '{"type":"session_meta","payload":{"cli_version":"0.8.0","cwd":"/test"}}',
+      '{"type":"response_item","payload":{"id":"item_001","type":"message","role":"user","content":[{"type":"input_text","text":"Read file"}]}}',
+      '{"type":"response_item","payload":{"id":"item_002","type":"function_call","call_id":"call_1","name":"read","arguments":"{\\"file\\":\\"foo.ts\\"}"}}',
+      '{"type":"response_item","payload":{"id":"item_003","type":"function_call_output","call_id":"call_1","output":"file contents"}}',
+      '{"type":"response_item","payload":{"id":"item_004","type":"message","role":"assistant","content":[{"type":"output_text","text":"Done."}]}}',
+    ].join("\n")
+
+    const result = SessionResume.parseLines(text)
+    expect(result.steps).toHaveLength(3)
+
+    const mid = result.steps[1]
+    expect(mid.role).toBe("assistant")
+    const tc = mid.parts.find((p): p is SessionResume.ToolCall => p.type === "tool_call")
+    const tr = mid.parts.find((p): p is SessionResume.ToolResult => p.type === "tool_result")
+    expect(tc).toBeDefined()
+    expect(tc!.id).toBe("call_1")
+    expect(tc!.name).toBe("read")
+    expect(tc!.input).toEqual({ file: "foo.ts" })
+    expect(tr).toBeDefined()
+    expect(tr!.callID).toBe("call_1")
+    expect(tr!.content).toBe("file contents")
+
+    expect(result.steps[2]).toEqual({ role: "assistant", parts: [{ type: "text", text: "Done." }] })
+  })
+
+  test("one user with two complete tool rounds produces exact steps in source order", () => {
+    const text = [
+      '{"type":"session_meta","payload":{"cli_version":"0.8.0","cwd":"/test"}}',
+      '{"type":"response_item","payload":{"id":"item_001","type":"message","role":"user","content":[{"type":"input_text","text":"Read then edit"}]}}',
+      '{"type":"response_item","payload":{"id":"item_002","type":"function_call","call_id":"c1","name":"read","arguments":"{}"}}',
+      '{"type":"response_item","payload":{"id":"item_003","type":"function_call_output","call_id":"c1","output":"result1"}}',
+      '{"type":"response_item","payload":{"id":"item_004","type":"message","role":"assistant","content":[{"type":"output_text","text":"Done reading. Now editing."}]}}',
+      '{"type":"response_item","payload":{"id":"item_005","type":"function_call","call_id":"c2","name":"edit","arguments":"{}"}}',
+      '{"type":"response_item","payload":{"id":"item_006","type":"function_call_output","call_id":"c2","output":"result2"}}',
+      '{"type":"response_item","payload":{"id":"item_007","type":"message","role":"assistant","content":[{"type":"output_text","text":"All done."}]}}',
+    ].join("\n")
+
+    const result = SessionResume.parseLines(text)
+    expect(result.steps).toHaveLength(4)
+
+    // Step 0: user
+    expect(result.steps[0].role).toBe("user")
+    expect(result.steps[0].parts).toEqual([{ type: "text", text: "Read then edit" }])
+
+    // Step 1: first assistant tool round
+    expect(result.steps[1].role).toBe("assistant")
+    const step1Types = result.steps[1].parts.map((p) => p.type)
+    expect(step1Types).toEqual(["tool_call", "tool_result"])
+    const step1Call = result.steps[1].parts[0] as SessionResume.ToolCall
+    expect(step1Call.id).toBe("c1")
+    expect(step1Call.name).toBe("read")
+    const step1Text = result.steps[2].parts[0] as SessionResume.TextPart
+    expect(step1Text.text).toBe("Done reading. Now editing.")
+
+    // Step 2 continues the new assistant step with the second tool round.
+    const step2Types = result.steps[2].parts.map((p) => p.type)
+    expect(step2Types).toEqual(["text", "tool_call", "tool_result"])
+    const step2Call = result.steps[2].parts[1] as SessionResume.ToolCall
+    expect(step2Call.id).toBe("c2")
+    expect(step2Call.name).toBe("edit")
+    const step2Text = result.steps[3].parts[0] as SessionResume.TextPart
+    expect(step2Text.text).toBe("All done.")
+  })
+
+  test("pairs multiple tool calls with results", () => {
+    const text = [
+      '{"type":"session_meta","payload":{"cli_version":"0.8.0","cwd":"/test"}}',
+      '{"type":"response_item","payload":{"id":"item_001","type":"message","role":"user","content":[{"type":"input_text","text":"Do two things"}]}}',
+      '{"type":"response_item","payload":{"id":"item_002","type":"function_call","call_id":"c1","name":"read","arguments":"{}"}}',
+      '{"type":"response_item","payload":{"id":"item_003","type":"function_call","call_id":"c2","name":"edit","arguments":"{}"}}',
+      '{"type":"response_item","payload":{"id":"item_004","type":"function_call_output","call_id":"c1","output":"r1"}}',
+      '{"type":"response_item","payload":{"id":"item_005","type":"function_call_output","call_id":"c2","output":"r2"}}',
+      '{"type":"response_item","payload":{"id":"item_006","type":"message","role":"assistant","content":[{"type":"output_text","text":"Both done."}]}}',
+    ].join("\n")
+
+    const result = SessionResume.parseLines(text)
+    const mid = result.steps[1]
+    expect(mid.role).toBe("assistant")
+    const calls = mid.parts.filter((p): p is SessionResume.ToolCall => p.type === "tool_call")
+    const results = mid.parts.filter((p): p is SessionResume.ToolResult => p.type === "tool_result")
+    expect(calls).toHaveLength(2)
+    expect(results).toHaveLength(2)
+    expect(calls.map((c) => c.id).sort()).toEqual(["c1", "c2"])
+    expect(results.map((r) => r.callID).sort()).toEqual(["c1", "c2"])
+  })
+
+  test("converts unpaired Codex tool call to terminal error", () => {
+    const text = [
+      '{"type":"session_meta","payload":{"cli_version":"0.8.0","cwd":"/test"}}',
+      '{"type":"response_item","payload":{"id":"item_001","type":"message","role":"user","content":[{"type":"input_text","text":"Go"}]}}',
+      '{"type":"response_item","payload":{"id":"item_002","type":"function_call","call_id":"orphan","name":"read","arguments":"{}"}}',
+      '{"type":"response_item","payload":{"id":"item_003","type":"message","role":"user","content":[{"type":"input_text","text":"Next topic"}]}}',
+    ].join("\n")
+
+    const result = SessionResume.parseLines(text)
+    const mid = result.steps[1]
+    expect(mid.role).toBe("assistant")
+    const errors = mid.parts.filter((p): p is SessionResume.ErrorPart => p.type === "error")
+    expect(errors).toHaveLength(1)
+    expect(errors[0].message).toContain("Unpaired tool call")
+    expect(errors[0].message).toContain("orphan")
+  })
+
+  test("handles orphan tool output (no matching call)", () => {
+    const text = [
+      '{"type":"session_meta","payload":{"cli_version":"0.8.0","cwd":"/test"}}',
+      '{"type":"response_item","payload":{"id":"item_001","type":"message","role":"user","content":[{"type":"input_text","text":"Go"}]}}',
+      '{"type":"response_item","payload":{"id":"item_002","type":"function_call_output","call_id":"no_match","output":"orphan"}}',
+    ].join("\n")
+
+    const result = SessionResume.parseLines(text)
+    expect(result.unsupported).toBe(1)
+  })
+
+  test("handles repeated call IDs across rounds", () => {
+    const text = [
+      '{"type":"session_meta","payload":{"cli_version":"0.8.0","cwd":"/test"}}',
+      '{"type":"response_item","payload":{"id":"item_001","type":"message","role":"user","content":[{"type":"input_text","text":"First"}]}}',
+      '{"type":"response_item","payload":{"id":"item_002","type":"function_call","call_id":"call_01","name":"read","arguments":"{\\"f\\":\\"a\\"}"}}',
+      '{"type":"response_item","payload":{"id":"item_003","type":"function_call_output","call_id":"call_01","output":"result a"}}',
+      '{"type":"response_item","payload":{"id":"item_004","type":"message","role":"assistant","content":[{"type":"output_text","text":"Done first."}]}}',
+      '{"type":"response_item","payload":{"id":"item_005","type":"message","role":"user","content":[{"type":"input_text","text":"Second"}]}}',
+      '{"type":"response_item","payload":{"id":"item_006","type":"function_call","call_id":"call_01","name":"read","arguments":"{\\"f\\":\\"b\\"}"}}',
+      '{"type":"response_item","payload":{"id":"item_007","type":"function_call_output","call_id":"call_01","output":"result b"}}',
+      '{"type":"response_item","payload":{"id":"item_008","type":"message","role":"assistant","content":[{"type":"output_text","text":"Done second."}]}}',
+    ].join("\n")
+
+    const result = SessionResume.parseLines(text)
+    const toolSteps = result.steps.filter(
+      (s) => s.role === "assistant" && s.parts.some((p) => p.type === "tool_call"),
+    )
+    expect(toolSteps).toHaveLength(2)
+
+    for (const step of toolSteps) {
+      const tr = step.parts.find((p): p is SessionResume.ToolResult => p.type === "tool_result")
+      expect(tr).toBeDefined()
+      expect(tr!.callID).toBe("call_01")
+    }
+  })
+
+  test("handles encrypted reasoning (empty summary)", () => {
+    const text = [
+      '{"type":"session_meta","payload":{"cli_version":"0.8.0","cwd":"/test"}}',
+      '{"type":"response_item","payload":{"id":"item_001","type":"message","role":"user","content":[{"type":"input_text","text":"Think deeply"}]}}',
+      '{"type":"response_item","payload":{"id":"item_002","type":"reasoning","summary":[]}}',
+      '{"type":"response_item","payload":{"id":"item_003","type":"message","role":"assistant","content":[{"type":"output_text","text":"Answer"}]}}',
+    ].join("\n")
+
+    const result = SessionResume.parseLines(text)
+    expect(result.unsupported).toBe(1)
+    expect(result.steps).toHaveLength(2)
+  })
+
+  test("counts empty assistant content as unsupported", () => {
+    const text = [
+      '{"type":"session_meta","payload":{"cli_version":"0.8.0","cwd":"/test"}}',
+      '{"type":"response_item","payload":{"id":"item_001","type":"message","role":"user","content":[{"type":"input_text","text":"Test"}]}}',
+      '{"type":"response_item","payload":{"id":"item_002","type":"message","role":"assistant","content":[]}}',
+    ].join("\n")
+
+    const result = SessionResume.parseLines(text)
+    expect(result.unsupported).toBe(1)
+    expect(result.steps).toHaveLength(1) // only the user step
+  })
+
+  test("skips turn_context, event_msg, and world_state records", () => {
+    const text = [
+      '{"type":"session_meta","payload":{"cli_version":"0.8.0","cwd":"/test"}}',
+      '{"type":"response_item","payload":{"id":"item_001","type":"message","role":"user","content":[{"type":"input_text","text":"Hello"}]}}',
+      '{"type":"turn_context","payload":{}}',
+      '{"type":"event_msg","payload":{}}',
+      '{"type":"world_state","payload":{}}',
+      '{"type":"response_item","payload":{"id":"item_002","type":"message","role":"assistant","content":[{"type":"output_text","text":"Hi"}]}}',
+    ].join("\n")
+
+    const result = SessionResume.parseLines(text)
+    expect(result.steps).toHaveLength(2)
+  })
+
+  test("handles partial tool results within one round", () => {
+    const text = [
+      '{"type":"session_meta","payload":{"cli_version":"0.8.0","cwd":"/test"}}',
+      '{"type":"response_item","payload":{"id":"item_001","type":"message","role":"user","content":[{"type":"input_text","text":"Go"}]}}',
+      '{"type":"response_item","payload":{"id":"item_002","type":"function_call","call_id":"ok","name":"ok","arguments":"{}"}}',
+      '{"type":"response_item","payload":{"id":"item_003","type":"function_call","call_id":"missing","name":"missing","arguments":"{}"}}',
+      '{"type":"response_item","payload":{"id":"item_004","type":"function_call_output","call_id":"ok","output":"done"}}',
+      '{"type":"response_item","payload":{"id":"item_005","type":"message","role":"user","content":[{"type":"input_text","text":"Continuing."}]}}',
+    ].join("\n")
+
+    const result = SessionResume.parseLines(text)
+    const mid = result.steps[1]
+    expect(mid.role).toBe("assistant")
+    const results = mid.parts.filter((p): p is SessionResume.ToolResult => p.type === "tool_result")
+    const errors = mid.parts.filter((p): p is SessionResume.ErrorPart => p.type === "error")
+
+    expect(results).toHaveLength(1)
+    expect(results[0].callID).toBe("ok")
+    expect(errors).toHaveLength(1)
+    expect(errors[0].message).toContain("missing")
+  })
+
+  test("handles custom_tool_call and custom_tool_call_output", () => {
+    const text = [
+      '{"type":"session_meta","payload":{"cli_version":"0.8.0","cwd":"/test"}}',
+      '{"type":"response_item","payload":{"id":"item_001","type":"message","role":"user","content":[{"type":"input_text","text":"Run custom tool"}]}}',
+      '{"type":"response_item","payload":{"id":"item_002","type":"custom_tool_call","call_id":"ct_01","name":"my-tool","input":{"key":"value"}}}',
+      '{"type":"response_item","payload":{"id":"item_003","type":"custom_tool_call_output","call_id":"ct_01","output":"custom result"}}',
+      '{"type":"response_item","payload":{"id":"item_004","type":"message","role":"assistant","content":[{"type":"output_text","text":"Done."}]}}',
+    ].join("\n")
+
+    const result = SessionResume.parseLines(text)
+    const mid = result.steps[1]
+    expect(mid.role).toBe("assistant")
+    const tc = mid.parts.find((p): p is SessionResume.ToolCall => p.type === "tool_call")
+    expect(tc).toBeDefined()
+    expect(tc!.id).toBe("ct_01")
+    expect(tc!.name).toBe("my-tool")
+    expect(tc!.input).toEqual({ key: "value" })
+
+    const tr = mid.parts.find((p): p is SessionResume.ToolResult => p.type === "tool_result")
+    expect(tr).toBeDefined()
+    expect(tr!.callID).toBe("ct_01")
+    expect(tr!.content).toBe("custom result")
+  })
+
+  test("rejects empty input", () => {
+    expect(() => SessionResume.parseLines("")).toThrow(SessionResume.ParseError)
+  })
+
+  test("rejects malformed JSON", () => {
+    expect(() =>
+      SessionResume.parseLines(
+        '{"type":"session_meta","payload":{"cli_version":"0.8.0"}}\n{broken',
+      ),
+    ).toThrow(SessionResume.ParseError)
+  })
+})
+
+// ── Discovery ────────────────────────────────────────────────────
+
+describe("SessionResume discovery", () => {
+  const id = "550e8400-e29b-41d4-a716-446655440000"
+
+  test("uses the Claude project slug and injected root", () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "resume-claude-"))
+    try {
+      const cwd = "/Users/test/project"
+      const directory = path.join(root, SessionResume.claudeProjectSlug(cwd))
+      fs.mkdirSync(directory, { recursive: true })
+      const expected = path.join(directory, `${id}.jsonl`)
+      fs.writeFileSync(expected, "{}")
+
+      expect(SessionResume.discoverClaude({ claude: root, cwd, id })).toEqual([expected])
+      expect(() => SessionResume.discoverClaude({ claude: root, cwd, id: "bad" })).toThrow(
+        SessionResume.ParseError,
+      )
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  test("lists only UUID Claude transcript names", () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "resume-claude-"))
+    try {
+      const cwd = "/Users/test/project"
+      const directory = path.join(root, SessionResume.claudeProjectSlug(cwd))
+      fs.mkdirSync(directory, { recursive: true })
+      fs.writeFileSync(path.join(directory, "agent.jsonl"), "{}")
+      fs.writeFileSync(path.join(directory, "550e8400-e29b-41d4-a716-446655440000.jsonl"), "{}")
+
+      expect(SessionResume.discoverClaude({ claude: root, cwd }).map((file) => path.basename(file))).toEqual([
+        "550e8400-e29b-41d4-a716-446655440000.jsonl",
+      ])
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  test("scans Codex rollouts from an injected root", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "resume-codex-"))
+    try {
+      const directory = path.join(root, "2026", "08", "03")
+      fs.mkdirSync(directory, { recursive: true })
+      const expected = path.join(directory, `rollout-2026-08-03T10-00-00-${id}.jsonl`)
+      fs.writeFileSync(expected, '{"type":"session_meta","payload":{"cwd":"/repo"}}\n')
+
+      await expect(SessionResume.discoverCodex({ codex: root, cwd: "/repo", id })).resolves.toEqual([expected])
+      await expect(SessionResume.discoverCodex({ codex: root, cwd: "/repo", id: "bad" })).rejects.toThrow(
+        SessionResume.ParseError,
+      )
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  test("scans a Codex rollout stored at the sessions root", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "resume-codex-"))
+    try {
+      const expected = path.join(root, `rollout-2026-08-03T10-00-00-${id}.jsonl`)
+      fs.writeFileSync(expected, '{"type":"session_meta","payload":{"cwd":"/repo"}}\n')
+
+      await expect(SessionResume.discoverCodex({ codex: root, cwd: "/repo", id })).resolves.toEqual([expected])
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  test("no-ID discovery matches cwd with backslash-separated paths (Windows)", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "resume-codex-"))
+    try {
+      const cwd = "C:\\Users\\dev\\project"
+      const file = path.join(root, `rollout-2026-08-03T10-00-00-${id}.jsonl`)
+      // Escaped backslashes in JSON are valid on all platforms
+      fs.writeFileSync(file, '{"type":"session_meta","payload":{"cwd":"C:\\\\Users\\\\dev\\\\project"}}\n')
+
+      await expect(SessionResume.discoverCodex({ codex: root, cwd })).resolves.toEqual([file])
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true })
+    }
+  })
+})
+
+// ── Full file parsing ────────────────────────────────────────────
+
+describe("parse file", () => {
+  test("parses claude.jsonl fixture with exact step count", async () => {
+    const result = await SessionResume.parse(
+      __dirname + "/fixture/session-resume/claude.jsonl",
+    )
+    expect(result.format).toBe("claude")
+    expect(result.version).toBe(2)
+
+    // 13 steps: user + 6 assistant tool rounds + interleaved text assistants
+    expect(result.steps.length).toBe(13)
+
+    // First step is user
+    expect(result.steps[0].role).toBe("user")
+    expect(result.steps[0].parts[0].type).toBe("text")
+
+    // Steps alternate between user and assistant
+    const roles = result.steps.map((s) => s.role)
+    expect(roles[0]).toBe("user")
+
+    // Has tool calls in at least 3 distinct steps
+    const toolSteps = result.steps.filter((s) =>
+      s.parts.some((p) => p.type === "tool_call"),
+    )
+    expect(toolSteps.length).toBeGreaterThanOrEqual(3)
+
+    // Has reasoning
+    const reasoningSteps = result.steps.filter((s) =>
+      s.parts.some((p) => p.type === "reasoning"),
+    )
+    expect(reasoningSteps.length).toBeGreaterThanOrEqual(1)
+
+    // Unsported content: redacted_thinking + custom_block + server_tool_result in user msg_017
+    expect(result.unsupported).toBe(3)
+  })
+
+  test("parses codex.jsonl fixture with exact step count", async () => {
+    const result = await SessionResume.parse(
+      __dirname + "/fixture/session-resume/codex.jsonl",
+    )
+    expect(result.format).toBe("codex")
+    expect(result.version).toBe(0)
+
+    expect(result.steps.length).toBe(14)
+
+    // First step is user
+    expect(result.steps[0].role).toBe("user")
+    expect(result.steps[0].parts[0].type).toBe("text")
+
+    // Has both user and assistant
+    const roleSet = new Set(result.steps.map((s) => s.role))
+    expect(roleSet.has("user")).toBe(true)
+    expect(roleSet.has("assistant")).toBe(true)
+
+    // Has tool calls in multiple steps (two distinct tool rounds)
+    const toolSteps = result.steps.filter((s) =>
+      s.parts.some((p) => p.type === "tool_call"),
+    )
+    expect(toolSteps.length).toBeGreaterThanOrEqual(2)
+
+    // Has unsupported content from encrypted reasoning + empty assistant
+    expect(result.unsupported).toBeGreaterThanOrEqual(2)
+  })
+
+  test("codex fixture: first user produces two complete assistant tool rounds", async () => {
+    const result = await SessionResume.parse(
+      __dirname + "/fixture/session-resume/codex.jsonl",
+    )
+
+    // Step 0: user
+    expect(result.steps[0].role).toBe("user")
+    expect(result.steps[0].parts[0].type).toBe("text")
+
+    // Step 1: first completed tool round.
+    expect(result.steps[1].role).toBe("assistant")
+    const step1Types = result.steps[1].parts.map((p) => p.type)
+    expect(step1Types).toContain("tool_call")
+    expect(step1Types).toContain("tool_result")
+    const step1Call = result.steps[1].parts.find(
+      (p): p is SessionResume.ToolCall => p.type === "tool_call",
+    )
+    expect(step1Call).toBeDefined()
+    expect(step1Call!.name).toBe("read")
+
+    // Step 2 starts the next assistant content and tool round.
+    expect(result.steps[2].role).toBe("assistant")
+    const step2Calls = result.steps[2].parts.filter(
+      (p): p is SessionResume.ToolCall => p.type === "tool_call",
+    )
+    expect(step2Calls.length).toBe(2)
+    const step2Results = result.steps[2].parts.filter(
+      (p): p is SessionResume.ToolResult => p.type === "tool_result",
+    )
+    expect(step2Results.length).toBe(2)
+    const step2Texts = result.steps[2].parts.filter(
+      (p): p is SessionResume.TextPart => p.type === "text",
+    )
+    expect(step2Texts.length).toBeGreaterThanOrEqual(1)
+  })
+
+  test("claude fixture: consecutive assistants before tool result merged into one step", async () => {
+    const result = await SessionResume.parse(
+      __dirname + "/fixture/session-resume/claude.jsonl",
+    )
+
+    // msg_018 (redacted_thinking), msg_019 (custom_block), msg_020 (tool_use)
+    // should be merged into a single assistant step
+    const lastAssistant = result.steps[result.steps.length - 1]
+    expect(lastAssistant.role).toBe("assistant")
+
+    const partTypes = lastAssistant.parts.map((p) => p.type)
+    // Should contain unsupported, unsupported, tool_call, error (from markUnpaired)
+    expect(partTypes.filter((t) => t === "unsupported").length).toBe(2)
+    expect(partTypes.filter((t) => t === "tool_call").length).toBe(1)
+    expect(partTypes.filter((t) => t === "error").length).toBe(1)
+  })
+
+  test("claude fixture: sidechain and metadata records excluded", async () => {
+    const result = await SessionResume.parse(
+      __dirname + "/fixture/session-resume/claude.jsonl",
+    )
+
+    // The fixture has 22 lines total, but 2 are metadata/sidechain records
+    // (ai-title line 7, last-prompt line 14)
+    // Verify no step contains sidechain text
+    for (const step of result.steps) {
+      for (const part of step.parts) {
+        if (part.type === "text") {
+          expect(part.text).not.toContain("Session title")
+        }
+      }
+    }
+  })
+
+  test("claude fixture: repeated IDs across rounds handled correctly", async () => {
+    const result = await SessionResume.parse(
+      __dirname + "/fixture/session-resume/claude.jsonl",
+    )
+
+    // toolu_01 appears in two different rounds (msg_002 and msg_014)
+    const toolSteps = result.steps.filter(
+      (s) =>
+        s.role === "assistant" &&
+        s.parts.some((p) => p.type === "tool_call" && p.id === "toolu_01"),
+    )
+    expect(toolSteps.length).toBe(2)
+  })
+
+  test("codex fixture: repeated call IDs across rounds", async () => {
+    const result = await SessionResume.parse(
+      __dirname + "/fixture/session-resume/codex.jsonl",
+    )
+
+    // call_01 appears in two different rounds
+    const call01Steps = result.steps.filter(
+      (s) =>
+        s.role === "assistant" &&
+        s.parts.some((p) => p.type === "tool_call" && p.id === "call_01"),
+    )
+    expect(call01Steps.length).toBe(2)
+  })
+
+  test("codex fixture: missing session_meta is rejected", () => {
+    const text = [
+      '{"type":"response_item","payload":{"id":"item_001","type":"message","role":"user","content":[{"type":"input_text","text":"Hello"}]}}',
+    ].join("\n")
+
+    expect(() => SessionResume.parseLines(text)).toThrow(SessionResume.ParseError)
+  })
+
+  test("rejects missing file", async () => {
+    await expect(SessionResume.parse("/nonexistent/file.jsonl")).rejects.toThrow()
+  })
+})
+
+// ── Unrecognized format rejection ────────────────────────────────
+
+describe("rejection", () => {
+  test("rejects unrecognized format", () => {
+    expect(() => SessionResume.parseLines('[1,2,3]')).toThrow(SessionResume.ParseError)
+    expect(() => SessionResume.parseLines('{"key":"value"}')).toThrow(SessionResume.ParseError)
+  })
+})
diff --git a/packages/opencode/test/kilocode/sessions/remote-command.test.ts b/packages/opencode/test/kilocode/sessions/remote-command.test.ts
index 614df8b0f63..3797bf138dc 100644
--- a/packages/opencode/test/kilocode/sessions/remote-command.test.ts
+++ b/packages/opencode/test/kilocode/sessions/remote-command.test.ts
@@ -727,6 +727,50 @@ describe("RemoteCommand", () => {
 
   // Even when the catalog advertises "compact" (the synthesized built-in),
   // a name not in the catalog must still be rejected.
+  test("resume commands appear from the current catalog", () => {
+    const catalog = RemoteCommand.build([
+      {
+        name: "resume-claude",
+        description: "import a Claude Code session transcript",
+        source: "command",
+        hints: ["$ARGUMENTS"],
+        template: "must-not-leak",
+      },
+      {
+        name: "resume-codex",
+        description: "import an OpenAI Codex session transcript",
+        source: "command",
+        hints: ["$ARGUMENTS"],
+        template: "must-not-leak",
+      },
+    ])
+
+    const names = catalog.commands.map((item) => item.name)
+    expect(names).toContain("resume-claude")
+    expect(names).toContain("resume-codex")
+    expect(names).toContain("compact")
+    expect(JSON.stringify(catalog)).not.toContain("template")
+    expect(JSON.stringify(catalog)).not.toContain("must-not-leak")
+    expect(catalog.commands.find((item) => item.name === "resume-claude")?.source).toBe("command")
+    expect(catalog.commands.find((item) => item.name === "resume-codex")?.source).toBe("command")
+  })
+
+  test("resume commands disappear from a catalog without them", () => {
+    const catalog = RemoteCommand.build([
+      {
+        name: "review",
+        description: "Review changes",
+        source: "command",
+        hints: ["$ARGUMENTS"],
+        template: "must-not-leak",
+      },
+    ])
+
+    const names = catalog.commands.map((item) => item.name)
+    expect(names).not.toContain("resume-claude")
+    expect(names).not.toContain("resume-codex")
+  })
+
   test("execute rejects arbitrary names even when the catalog advertises built-in compact", async () => {
     const calls: unknown[] = []
     const remote = RemoteCommand.create({
diff --git a/packages/opencode/test/kilocode/tool/grep-signal-controls.test.ts b/packages/opencode/test/kilocode/tool/grep-signal-controls.test.ts
deleted file mode 100644
index e6447866ea1..00000000000
--- a/packages/opencode/test/kilocode/tool/grep-signal-controls.test.ts
+++ /dev/null
@@ -1,192 +0,0 @@
-import { describe, expect } from "bun:test"
-import { Effect, Exit, Layer, Schema } from "effect"
-import path from "path"
-import { CrossSpawnSpawner } from "@opencode-ai/core/cross-spawn-spawner"
-import { FSUtil } from "@opencode-ai/core/fs-util"
-import { Ripgrep } from "@opencode-ai/core/ripgrep"
-import { Agent } from "../../../src/agent/agent"
-import { Git } from "../../../src/git"
-import { GrepTool, Parameters } from "../../../src/tool/grep"
-import { Truncate } from "../../../src/tool/truncate"
-import { MessageID, SessionID } from "../../../src/session/schema"
-import { TestInstance } from "../../fixture/fixture"
-import { testEffect } from "../../lib/effect"
-
-const it = testEffect(
-  Layer.mergeAll(
-    CrossSpawnSpawner.defaultLayer,
-    FSUtil.defaultLayer,
-    Ripgrep.defaultLayer,
-    Truncate.defaultLayer,
-    Agent.defaultLayer,
-    Git.defaultLayer,
-  ),
-)
-
-const ctx = {
-  sessionID: SessionID.make("ses_grep_signal_controls"),
-  messageID: MessageID.make("msg_grep_signal_controls"),
-  callID: "",
-  agent: "code",
-  abort: AbortSignal.any([]),
-  messages: [],
-  metadata: () => Effect.void,
-  ask: () => Effect.void,
-}
-
-const file = (test: { readonly directory: string }, name: string) => path.join(test.directory, name)
-
-const init = Effect.gen(function* () {
-  const info = yield* GrepTool
-  return yield* info.init()
-})
-
-describe("Kilo grep signal-to-noise controls", () => {
-  it.effect("validates signal controls", () =>
-    Effect.sync(() => {
-      expect(Schema.decodeUnknownSync(Parameters)({ pattern: "needle", context: 0, limit: 1 })).toMatchObject({
-        context: 0,
-        limit: 1,
-      })
-      expect(() => Schema.decodeUnknownSync(Parameters)({ pattern: "needle", context: -1 })).toThrow()
-      expect(() => Schema.decodeUnknownSync(Parameters)({ pattern: "needle", limit: 0 })).toThrow()
-      expect(() => Schema.decodeUnknownSync(Parameters)({ pattern: "needle", limit: 1.5 })).toThrow()
-    }),
-  )
-
-  it.instance("preserves the default match output", () =>
-    Effect.gen(function* () {
-      const test = yield* TestInstance
-      yield* Effect.promise(() => Bun.write(file(test, "default.txt"), "before\nneedle\nafter\n"))
-      const grep = yield* init
-      const result = yield* grep.execute({ pattern: "needle", path: test.directory }, ctx)
-
-      expect(result.metadata.matches).toBe(1)
-      expect(result.output).toContain("Line 2: needle")
-      expect(result.output).not.toContain("[match]")
-    }),
-  )
-
-  it.instance("stops after the custom match limit", () =>
-    Effect.gen(function* () {
-      const test = yield* TestInstance
-      yield* Effect.promise(() =>
-        Bun.write(file(test, "many.txt"), `${Array.from({ length: 20 }, () => "needle").join("\n")}\n`),
-      )
-      const grep = yield* init
-      const result = yield* grep.execute({ pattern: "needle", path: test.directory, limit: 2 }, ctx)
-
-      expect(result.metadata.matches).toBe(2)
-      expect(result.metadata.truncated).toBe(true)
-      expect(result.output).toContain("2 matches limit reached. Use limit=4 for more, or refine pattern.")
-      expect(result.output).not.toContain("(Results truncated")
-      expect(result.output).not.toContain("Line 3: needle")
-    }),
-  )
-
-  it.instance("supports literal and case-insensitive matching", () =>
-    Effect.gen(function* () {
-      const test = yield* TestInstance
-      yield* Effect.promise(() =>
-        Promise.all([
-          Bun.write(file(test, "literal.txt"), "a.*b\n"),
-          Bun.write(file(test, "regex.txt"), "azb\n"),
-          Bun.write(file(test, "case.txt"), "Needle\n"),
-        ]),
-      )
-      const grep = yield* init
-      const literal = yield* grep.execute({ pattern: "a.*b", path: test.directory, literal: true }, ctx)
-      const insensitive = yield* grep.execute({ pattern: "needle", path: test.directory, ignoreCase: true }, ctx)
-
-      expect(literal.metadata.matches).toBe(1)
-      expect(literal.output).toContain("literal.txt")
-      expect(literal.output).not.toContain("regex.txt")
-      expect(insensitive.metadata.matches).toBe(1)
-      expect(insensitive.output).toContain("case.txt")
-    }),
-  )
-
-  it.instance("formats only bounded context around returned matches", () =>
-    Effect.gen(function* () {
-      const test = yield* TestInstance
-      yield* Effect.promise(() =>
-        Bun.write(
-          file(test, "context.txt"),
-          ["before", "needle", "after", "far", "later needle", "later after"].join("\n") + "\n",
-        ),
-      )
-      const grep = yield* init
-      const result = yield* grep.execute({ pattern: "needle", path: test.directory, context: 1, limit: 1 }, ctx)
-
-      expect(result.metadata.matches).toBe(1)
-      expect(result.output).toContain("[context] Line 1: before")
-      expect(result.output).toContain("[match] Line 2: needle")
-      expect(result.output).toContain("[context] Line 3: after")
-      expect(result.output).not.toContain("Line 4: far")
-      expect(result.output).not.toContain("later needle")
-    }),
-  )
-
-  it.instance("does not count context lines toward the match limit", () =>
-    Effect.gen(function* () {
-      const test = yield* TestInstance
-      const content = Array.from(
-        { length: 35 },
-        (_, index) => `before-${index}\nneedle-${index}\nafter-${index}\ngap-${index}`,
-      ).join("\n")
-      yield* Effect.promise(() => Bun.write(file(test, "context-limit.txt"), `${content}\n`))
-      const grep = yield* init
-      const result = yield* grep.execute({ pattern: "needle", path: test.directory, context: 1, limit: 100 }, ctx)
-
-      expect(result.metadata.matches).toBe(35)
-      expect(result.metadata.truncated).toBe(false)
-      expect(result.output).toContain("needle-34")
-      expect(result.output).not.toContain("matches limit reached")
-    }),
-  )
-
-  it.instance("guides the model to read truncated lines", () =>
-    Effect.gen(function* () {
-      const test = yield* TestInstance
-      yield* Effect.promise(() => Bun.write(file(test, "long.txt"), `${"x".repeat(2_100)}needle\n`))
-      const grep = yield* init
-      const result = yield* grep.execute({ pattern: "needle", path: test.directory }, ctx)
-
-      expect(result.metadata.matches).toBe(1)
-      expect(result.output).toContain("Some matching or context lines were truncated. Use read for full lines.")
-    }),
-  )
-
-  it.instance("retains include filtering", () =>
-    Effect.gen(function* () {
-      const test = yield* TestInstance
-      yield* Effect.promise(() =>
-        Promise.all([
-          Bun.write(file(test, "included.ts"), "needle\n"),
-          Bun.write(file(test, "excluded.txt"), "needle\n"),
-        ]),
-      )
-      const grep = yield* init
-      const result = yield* grep.execute({ pattern: "needle", path: test.directory, include: "*.ts" }, ctx)
-
-      expect(result.metadata.matches).toBe(1)
-      expect(result.output).toContain("included.ts")
-      expect(result.output).not.toContain("excluded.txt")
-    }),
-  )
-
-  it.instance("honors cancellation", () =>
-    Effect.gen(function* () {
-      const test = yield* TestInstance
-      yield* Effect.promise(() => Bun.write(file(test, "cancel.txt"), "needle\n".repeat(10_000)))
-      const grep = yield* init
-      const controller = new AbortController()
-      controller.abort()
-      const exit = yield* grep
-        .execute({ pattern: "needle", path: test.directory }, { ...ctx, abort: controller.signal })
-        .pipe(Effect.exit)
-
-      expect(Exit.isFailure(exit)).toBe(true)
-    }),
-  )
-})
diff --git a/packages/opencode/test/server/httpapi-v2-pty.test.ts b/packages/opencode/test/server/httpapi-v2-pty.test.ts
index d2eb68f77a9..db74a5b649d 100644
--- a/packages/opencode/test/server/httpapi-v2-pty.test.ts
+++ b/packages/opencode/test/server/httpapi-v2-pty.test.ts
@@ -14,6 +14,11 @@ import { resetDatabase } from "../fixture/db"
 import { disposeAllInstances, tmpdir, tmpdirScoped } from "../fixture/fixture"
 import { testEffect } from "../lib/effect"
 
+// kilocode_change start - PTY route tests do not need an indexing worker per temp project;
+// detached indexing startup races PTY setup and can exhaust the Darwin test deadline.
+process.env.KILO_DISABLE_CODEBASE_INDEXING = "vscode-no-workspace"
+// kilocode_change end
+
 const context = Context.empty() as Context.Context<unknown>
 const testPty = process.platform === "win32" ? test.skip : test
 
diff --git a/packages/opencode/test/tool/__snapshots__/parameters.test.ts.snap b/packages/opencode/test/tool/__snapshots__/parameters.test.ts.snap
index a31700b7c0e..368225175b6 100644
--- a/packages/opencode/test/tool/__snapshots__/parameters.test.ts.snap
+++ b/packages/opencode/test/tool/__snapshots__/parameters.test.ts.snap
@@ -114,37 +114,16 @@ exports[`tool parameters JSON Schema (wire shape) grep 1`] = `
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "properties": {
-    "context": {
-      "description": "Number of context lines to show before and after each match (default 0)",
-      "maximum": 9007199254740991,
-      "minimum": 0,
-      "type": "integer",
-    },
-    "ignoreCase": {
-      "description": "Match without regard to letter case (default false)",
-      "type": "boolean",
-    },
     "include": {
       "description": "File pattern to include in the search (e.g. "*.js", "*.{ts,tsx}")",
       "type": "string",
     },
-    "limit": {
-      "description": "Maximum matching lines to return (default 100)",
-      "exclusiveMinimum": 0,
-      "maximum": 9007199254740991,
-      "minimum": -9007199254740991,
-      "type": "integer",
-    },
-    "literal": {
-      "description": "Treat pattern as plain text instead of a regex (default false)",
-      "type": "boolean",
-    },
     "path": {
       "description": "The directory to search in. Defaults to the current working directory.",
       "type": "string",
     },
     "pattern": {
-      "description": "Pattern to search for in file contents (regex by default)",
+      "description": "The regex pattern to search for in file contents",
       "type": "string",
     },
   },
diff --git a/packages/opencode/test/tool/grep.test.ts b/packages/opencode/test/tool/grep.test.ts
index 41e6a4004f8..630c355df31 100644
--- a/packages/opencode/test/tool/grep.test.ts
+++ b/packages/opencode/test/tool/grep.test.ts
@@ -149,7 +149,7 @@ describe("tool.grep", () => {
       const grep = yield* info.init()
       const result = yield* grep.execute({ pattern: "needle", path: test.directory, include: "*.txt" }, ctx)
 
-      expect(result.output).toContain("100 matches limit reached. Use limit=200 for more, or refine pattern.") // kilocode_change
+      expect(result.output).toContain("(Results truncated. Consider using a more specific path or pattern.)")
       expect(result.output).not.toMatch(/showing \d+ of \d+ matches/)
     }),
   )
diff --git a/packages/opencode/test/tool/tool-define.test.ts b/packages/opencode/test/tool/tool-define.test.ts
index 08e06043622..8d3431bac76 100644
--- a/packages/opencode/test/tool/tool-define.test.ts
+++ b/packages/opencode/test/tool/tool-define.test.ts
@@ -37,6 +37,19 @@ function makeTool(id: string, executeFn?: () => void) {
   }
 }
 
+// kilocode_change start
+function invalid(exit: Exit.Exit<unknown, unknown>) {
+  expect(Exit.isFailure(exit)).toBe(true)
+  if (!Exit.isFailure(exit)) {
+    throw new Error("expected tool execution to fail")
+  }
+  const die = exit.cause.reasons.find(Cause.isDieReason)
+  const error = die?.defect
+  expect(error).toBeInstanceOf(Tool.InvalidArgumentsError)
+  return error as Tool.InvalidArgumentsError
+}
+// kilocode_change end
+
 describe("Tool.define", () => {
   it.effect("object-defined tool does not mutate the original init object", () =>
     Effect.gen(function* () {
@@ -135,19 +148,68 @@ describe("Tool.define", () => {
 
       // Missing required `question` field on the first questions[] entry.
       const exit = yield* execute({ questions: [{ options: ["a"] }] }, makeCtx()).pipe(Effect.exit)
-      expect(Exit.isFailure(exit)).toBe(true)
-      if (!Exit.isFailure(exit)) return
-
-      // The wrap ends with Effect.orDie, so the failure lives in the cause as a
-      // defect. Recover the typed instance from there.
-      const die = exit.cause.reasons.find(Cause.isDieReason)
-      const error = die?.defect
-      expect(error).toBeInstanceOf(Tool.InvalidArgumentsError)
-      const args = error as Tool.InvalidArgumentsError
+      const args = invalid(exit) // kilocode_change
       expect(args.tool).toBe("qtest")
       expect(args.message).toContain("qtest tool was called with invalid arguments")
       expect(args.message).toContain("Please rewrite the input")
       expect(args.message).toContain(`["questions"][0]["question"]`)
     }),
   )
+
+  // kilocode_change start
+  it.effect("invalid args explain missing required scalar fields without SchemaError jargon", () =>
+    Effect.gen(function* () {
+      const parameters = Schema.Struct({
+        pattern: Schema.String,
+      })
+      const info = yield* Tool.define(
+        "grep",
+        Effect.succeed({
+          description: "test tool",
+          parameters,
+          execute() {
+            return Effect.succeed({ title: "ok", output: "ok", metadata: { truncated: false } })
+          },
+        }),
+      )
+      const tool = yield* info.init()
+      const execute = tool.execute as unknown as (args: unknown, ctx: Tool.Context) => ReturnType<typeof tool.execute>
+
+      const exit = yield* execute({}, makeCtx()).pipe(Effect.exit)
+      const args = invalid(exit)
+      expect(args.message).toContain("grep tool was called with invalid arguments")
+      expect(args.message).toContain("Please rewrite the input")
+      expect(args.detail).toContain(`["pattern"]`)
+      expect(args.detail.toLowerCase()).toContain("missing")
+      expect(args.detail.toLowerCase()).toContain("required")
+      expect(args.message).not.toContain("SchemaError(")
+    }),
+  )
+
+  it.effect("invalid args enumerate multiple failing fields", () =>
+    Effect.gen(function* () {
+      const parameters = Schema.Struct({
+        pattern: Schema.String,
+        path: Schema.String,
+      })
+      const info = yield* Tool.define(
+        "multi",
+        Effect.succeed({
+          description: "test tool",
+          parameters,
+          execute() {
+            return Effect.succeed({ title: "ok", output: "ok", metadata: { truncated: false } })
+          },
+        }),
+      )
+      const tool = yield* info.init()
+      const execute = tool.execute as unknown as (args: unknown, ctx: Tool.Context) => ReturnType<typeof tool.execute>
+
+      const exit = yield* execute({}, makeCtx()).pipe(Effect.exit)
+      const args = invalid(exit)
+      expect(args.detail).toContain(`["pattern"]`)
+      expect(args.detail).toContain(`["path"]`)
+    }),
+  )
+  // kilocode_change end
 })
diff --git a/packages/plugin-atomic-chat/package.json b/packages/plugin-atomic-chat/package.json
index 554a5f527bc..56cc83f5295 100644
--- a/packages/plugin-atomic-chat/package.json
+++ b/packages/plugin-atomic-chat/package.json
@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@kilocode/plugin-atomic-chat",
-  "version": "7.4.18",
+  "version": "7.4.20",
   "description": "Kilo Code plugin for Atomic Chat: auto-detection and dynamic model discovery (OpenAI-compatible local API)",
   "type": "module",
   "license": "MIT",
diff --git a/packages/plugin/package.json b/packages/plugin/package.json
index 305899105cc..dabbfd802b2 100644
--- a/packages/plugin/package.json
+++ b/packages/plugin/package.json
@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@kilocode/plugin",
-  "version": "7.4.18",
+  "version": "7.4.20",
   "type": "module",
   "license": "MIT",
   "scripts": {
diff --git a/packages/script/package.json b/packages/script/package.json
index 9c6851dab38..2148c375543 100644
--- a/packages/script/package.json
+++ b/packages/script/package.json
@@ -12,6 +12,6 @@
   "exports": {
     ".": "./src/index.ts"
   },
-  "version": "7.4.18",
+  "version": "7.4.20",
   "peerDependencies": {}
 }
diff --git a/packages/sdk/js/package.json b/packages/sdk/js/package.json
index f7f1d7ecda0..c9cb4a042cf 100644
--- a/packages/sdk/js/package.json
+++ b/packages/sdk/js/package.json
@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@kilocode/sdk",
-  "version": "7.4.18",
+  "version": "7.4.20",
   "type": "module",
   "license": "MIT",
   "scripts": {
diff --git a/packages/sdk/js/src/v2/gen/sdk.gen.ts b/packages/sdk/js/src/v2/gen/sdk.gen.ts
index 11c459be779..8c77db8ce01 100644
--- a/packages/sdk/js/src/v2/gen/sdk.gen.ts
+++ b/packages/sdk/js/src/v2/gen/sdk.gen.ts
@@ -211,6 +211,8 @@ import type {
   KiloFimResponses,
   KiloModelsImagesErrors,
   KiloModelsImagesResponses,
+  KiloModelsTranscriptionsErrors,
+  KiloModelsTranscriptionsResponses,
   KiloModesErrors,
   KiloModesResponses,
   KiloNotificationsErrors,
@@ -6855,6 +6857,40 @@ export class Models extends HeyApiClient {
       ...params,
     })
   }
+
+  /**
+   * Speech-to-text models
+   *
+   * List transcription-capable models from the Kilo Gateway catalog
+   */
+  public transcriptions<ThrowOnError extends boolean = false>(
+    parameters?: {
+      directory?: string
+      workspace?: string
+    },
+    options?: Options<never, ThrowOnError>,
+  ) {
+    const params = buildClientParams(
+      [parameters],
+      [
+        {
+          args: [
+            { in: "query", key: "directory" },
+            { in: "query", key: "workspace" },
+          ],
+        },
+      ],
+    )
+    return (options?.client ?? this.client).get<
+      KiloModelsTranscriptionsResponses,
+      KiloModelsTranscriptionsErrors,
+      ThrowOnError
+    >({
+      url: "/kilo/models/transcriptions",
+      ...options,
+      ...params,
+    })
+  }
 }
 
 export class Organization extends HeyApiClient {
diff --git a/packages/sdk/js/src/v2/gen/types.gen.ts b/packages/sdk/js/src/v2/gen/types.gen.ts
index f234bbed584..c2d1cea6ba8 100644
--- a/packages/sdk/js/src/v2/gen/types.gen.ts
+++ b/packages/sdk/js/src/v2/gen/types.gen.ts
@@ -1322,6 +1322,7 @@ export type PermissionConfig =
       bash?: PermissionRuleConfig
       task?: PermissionRuleConfig
       external_directory?: PermissionRuleConfig
+      markdown_source?: PermissionRuleConfig
       todowrite?: PermissionActionConfig
       question?: PermissionActionConfig
       webfetch?: PermissionActionConfig
@@ -12182,6 +12183,38 @@ export type KiloModelsImagesResponses = {
 
 export type KiloModelsImagesResponse = KiloModelsImagesResponses[keyof KiloModelsImagesResponses]
 
+export type KiloModelsTranscriptionsData = {
+  body?: never
+  path?: never
+  query?: {
+    directory?: string
+    workspace?: string
+  }
+  url: "/kilo/models/transcriptions"
+}
+
+export type KiloModelsTranscriptionsErrors = {
+  /**
+   * BadRequest | InvalidRequestError
+   */
+  400: EffectHttpApiErrorBadRequest | InvalidRequestError
+}
+
+export type KiloModelsTranscriptionsError = KiloModelsTranscriptionsErrors[keyof KiloModelsTranscriptionsErrors]
+
+export type KiloModelsTranscriptionsResponses = {
+  /**
+   * Speech-to-text model list
+   */
+  200: Array<{
+    id: string
+    name: string
+  }>
+}
+
+export type KiloModelsTranscriptionsResponse =
+  KiloModelsTranscriptionsResponses[keyof KiloModelsTranscriptionsResponses]
+
 export type KiloNotificationsData = {
   body?: never
   path?: never
diff --git a/packages/sdk/openapi.json b/packages/sdk/openapi.json
index 71ff553fff6..bba91e9b921 100644
--- a/packages/sdk/openapi.json
+++ b/packages/sdk/openapi.json
@@ -13953,6 +13953,81 @@
         ]
       }
     },
+    "/kilo/models/transcriptions": {
+      "get": {
+        "tags": ["kilo"],
+        "operationId": "kilo.models.transcriptions",
+        "parameters": [
+          {
+            "name": "directory",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            },
+            "required": false
+          },
+          {
+            "name": "workspace",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            },
+            "required": false
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Speech-to-text model list",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "id": {
+                        "type": "string"
+                      },
+                      "name": {
+                        "type": "string"
+                      }
+                    },
+                    "required": ["id", "name"],
+                    "additionalProperties": false
+                  },
+                  "description": "Speech-to-text model list"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "BadRequest | InvalidRequestError",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "anyOf": [
+                    {
+                      "$ref": "#/components/schemas/effect_HttpApiError_BadRequest"
+                    },
+                    {
+                      "$ref": "#/components/schemas/InvalidRequestError"
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        },
+        "description": "List transcription-capable models from the Kilo Gateway catalog",
+        "summary": "Speech-to-text models",
+        "x-codeSamples": [
+          {
+            "lang": "js",
+            "source": "import { createKiloClient } from \"@kilocode/sdk\"\n\nconst client = createKiloClient()\nawait client.kilo.models.transcriptions({\n  ...\n})"
+          }
+        ]
+      }
+    },
     "/kilo/notifications": {
       "get": {
         "tags": ["kilo"],
diff --git a/packages/server/package.json b/packages/server/package.json
index 04006121d84..ed1bdf9aa14 100644
--- a/packages/server/package.json
+++ b/packages/server/package.json
@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@opencode-ai/server",
-  "version": "7.4.18",
+  "version": "7.4.20",
   "private": true,
   "type": "module",
   "license": "MIT",
diff --git a/packages/storybook/package.json b/packages/storybook/package.json
index 56bc841220c..016b88f487b 100644
--- a/packages/storybook/package.json
+++ b/packages/storybook/package.json
@@ -26,7 +26,7 @@
     "typescript": "catalog:",
     "vite": "catalog:"
   },
-  "version": "7.4.18",
+  "version": "7.4.20",
   "dependencies": {},
   "peerDependencies": {}
 }
diff --git a/packages/tui/package.json b/packages/tui/package.json
index 3e241c725b4..8e46b53bd52 100644
--- a/packages/tui/package.json
+++ b/packages/tui/package.json
@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@opencode-ai/tui",
-  "version": "7.4.18",
+  "version": "7.4.20",
   "private": true,
   "type": "module",
   "license": "MIT",
diff --git a/packages/ui/package.json b/packages/ui/package.json
index 0346e145ec0..719c7aa513b 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@opencode-ai/ui",
-  "version": "7.4.18",
+  "version": "7.4.20",
   "type": "module",
   "license": "MIT",
   "exports": {
diff --git a/script/upstream/package.json b/script/upstream/package.json
index 6c10f20641e..9c1095b5766 100644
--- a/script/upstream/package.json
+++ b/script/upstream/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@kilocode/upstream-merge",
-  "version": "7.4.18",
+  "version": "7.4.20",
   "private": true,
   "type": "module",
   "description": "Scripts for automating upstream opencode merges into Kilo",