docs(release): prepare v1.25.0 notes (#8687)

Summary:
Generate a bilingual, product-focused draft from merged pull request metadata. Reuse the selected release-bound PR when one is available.

Verification:
Validate the catalog, citations, bilingual fields, and rendered GitHub release notes before committing.

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

desktop/frontend/bench/transcript-scroll-stability.mjs

@@ -52,12 +52,100 @@ try {
   await page.click('.project-tree__topic-main:has-text("bench:tools-38t")');
   await page.waitForFunction(() => document.querySelectorAll(".transcript__row").length > 4, undefined, { timeout: 30_000 });
   await page.waitForFunction(() => document.querySelector(".transcript")?.textContent?.includes("pkg-41/mod.go"), undefined, { timeout: 30_000 });
+  const markdownVisibility = await page.evaluate(() => {
+    const row = document.querySelector(".transcript__row");
+    if (!(row instanceof HTMLElement)) return { inside: null, outside: null };
+    const mount = (parent) => {
+      const host = document.createElement("div");
+      host.className = "md";
+      const probe = document.createElement("p");
+      host.append(probe);
+      parent.append(host);
+      const value = getComputedStyle(probe).contentVisibility;
+      host.remove();
+      return value;
+    };
+    return { inside: mount(row), outside: mount(document.body) };
+  });
+  assert(
+    markdownVisibility.inside === "visible",
+    `mounted transcript markdown stays measurable (${markdownVisibility.inside})`,
+  );
+  assert(
+    markdownVisibility.outside === "auto",
+    `markdown outside the transcript still culls with content-visibility (${markdownVisibility.outside})`,
+  );
 
   const transcript = page.locator(".transcript");
   const box = await transcript.boundingBox();
   assert(box != null, "bench exposes the Virtuoso transcript viewport");
   assert(await page.locator('[data-virtuoso-scroller="true"]').count() === 1, "Transcript is backed by React Virtuoso");
 
+  // Stay on the tail. Opening the workspace dock must not crop right-aligned
+  // user bubbles — that is a width/padding bug, not the scroll-up overlap.
+  const measureDockCrop = () => page.evaluate(() => {
+    const layout = document.querySelector(".layout");
+    const chat = document.querySelector(".chat-pane");
+    const dock = document.querySelector(".workbench-dock");
+    const scroller = document.querySelector(".transcript");
+    const bubbles = [...document.querySelectorAll(".msg--user .msg__body")];
+    const bubble = bubbles.at(-1);
+    if (!(chat instanceof HTMLElement) || !(bubble instanceof HTMLElement) || !(scroller instanceof HTMLElement)) {
+      return { ok: false };
+    }
+    const chatBox = chat.getBoundingClientRect();
+    const bubbleBox = bubble.getBoundingClientRect();
+    const dockBox = dock instanceof HTMLElement ? dock.getBoundingClientRect() : null;
+    return {
+      ok: true,
+      workspaceOpen: Boolean(layout?.classList.contains("layout--workspace-open")),
+      overflowChatRight: +(bubbleBox.right - chatBox.right).toFixed(2),
+      overflowDock: dockBox ? +(bubbleBox.right - dockBox.left).toFixed(2) : null,
+      fromBottom: +(scroller.scrollHeight - scroller.scrollTop - scroller.clientHeight).toFixed(2),
+    };
+  });
+  const dockOpen = await measureDockCrop();
+  assert(dockOpen.ok, "tail-follow dock check can see the chat and a user bubble");
+  assert(dockOpen.workspaceOpen === true, "bench starts with the workspace dock open");
+  assert(dockOpen.fromBottom <= 1, `dock-open check stays on the tail without scrolling up (${dockOpen.fromBottom})`);
+  assert(dockOpen.overflowChatRight <= 1, `user bubble stays inside the chat column with the dock open (${dockOpen.overflowChatRight})`);
+  assert(
+    dockOpen.overflowDock == null || dockOpen.overflowDock <= 1,
+    `user bubble does not extend into the workspace dock (${dockOpen.overflowDock})`,
+  );
+
+  // Width changes remasure Virtuoso and can leave a few pixels off the
+  // physical bottom. Keep the crop assertions tight; only the post-resize
+  // stick-to-tail check gets this slack (CI saw 7px after collapse).
+  const tailAfterResizePx = 16;
+  const waitNearTailAfterResize = () => page.waitForFunction((limit) => {
+    const scroller = document.querySelector(".transcript");
+    return Boolean(scroller && scroller.scrollHeight - scroller.scrollTop - scroller.clientHeight <= limit);
+  }, tailAfterResizePx);
+
+  const collapse = page.getByRole("button", { name: /Collapse workspace|收起工作区/ });
+  if (await collapse.count()) {
+    await collapse.click();
+    await page.waitForFunction(() => !document.querySelector(".layout")?.classList.contains("layout--workspace-open"));
+    await waitNearTailAfterResize();
+    const dockClosed = await measureDockCrop();
+    assert(dockClosed.ok && dockClosed.workspaceOpen === false, "workspace toggle collapses the dock");
+    assert(dockClosed.fromBottom <= tailAfterResizePx, `collapsing the dock does not require scrolling up (${dockClosed.fromBottom})`);
+    assert(dockClosed.overflowChatRight <= 1, `user bubble stays inside the chat column with the dock closed (${dockClosed.overflowChatRight})`);
+    const expand = page.getByRole("button", { name: /Expand workspace|展开工作区/ });
+    await expand.click();
+    await page.waitForFunction(() => Boolean(document.querySelector(".layout")?.classList.contains("layout--workspace-open")));
+    await waitNearTailAfterResize();
+    const dockReopen = await measureDockCrop();
+    assert(dockReopen.ok && dockReopen.workspaceOpen === true, "workspace toggle reopens the dock");
+    assert(dockReopen.fromBottom <= tailAfterResizePx, `reopening the dock stays on the tail (${dockReopen.fromBottom})`);
+    assert(dockReopen.overflowChatRight <= 1, `user bubble stays inside the chat column after reopening the dock (${dockReopen.overflowChatRight})`);
+    assert(
+      dockReopen.overflowDock == null || dockReopen.overflowDock <= 1,
+      `user bubble still does not enter the dock after reopen (${dockReopen.overflowDock})`,
+    );
+  }
+
   // Start away from either edge and record a visible stable row. Growing an
   // already-mounted row above it reproduces async Markdown/tool hydration.
   const beforeGrowth = await transcript.evaluate((element) => {

desktop/frontend/scripts/check-bundle-budget.mjs

@@ -75,9 +75,11 @@ if (localeChunks.length !== 2) {
 for (const path of localeChunks) {
   const name = basename(path);
   // Task Monitor, billing, indexed history, Task Center, Extension UI, and
-  // runtime controls plus execution-setting receipts add localized copy. Keep
-  // both dictionaries bounded.
-  const budget = name.startsWith("zh-TW-") ? 55.5 * 1024 : 54.5 * 1024;
+  // runtime controls plus execution-setting receipts add localized copy. The
+  // recovery "other saved versions" dialog adds ~0.1 KiB gzip to zh (54.6 over
+  // the old 54.5 gate, +0.18%); both on-demand dictionaries stay bounded with
+  // small headroom.
+  const budget = name.startsWith("zh-TW-") ? 55.5 * 1024 : 54.75 * 1024;
   assertBudget(`${name} gzip`, gzipBytes(path), budget);
 }
 

desktop/frontend/src/__tests__/hydrate-history-apply.test.ts

@@ -0,0 +1,63 @@
+// Run: tsx src/__tests__/hydrate-history-apply.test.ts
+
+import {
+  hasCachedLiveTurn,
+  sameSessionPlaceholderItems,
+  shouldApplyHydratedHistory,
+} from "../lib/hydrateHistoryApply";
+
+let passed = 0;
+let failed = 0;
+
+function ok(value: boolean, label: string) {
+  if (value) {
+    process.stdout.write(`  PASS  ${label}\n`);
+    passed += 1;
+  } else {
+    process.stdout.write(`  FAIL  ${label}\n`);
+    failed += 1;
+  }
+}
+
+console.log("\nhydrate history apply");
+
+ok(!shouldApplyHydratedHistory(true, true, false, { items: [] }), "skipHistory blocks apply");
+ok(!shouldApplyHydratedHistory(false, false, false, { items: [] }), "missing projection blocks apply");
+ok(shouldApplyHydratedHistory(false, true, false, { items: [] }), "idle empty surface applies history");
+ok(
+  shouldApplyHydratedHistory(false, true, true, { running: true, items: [] }),
+  "running empty surface applies history",
+);
+ok(
+  !shouldApplyHydratedHistory(false, true, true, {
+    running: true,
+    items: [{ kind: "user" }],
+  }),
+  "running visible transcript is not replaced",
+);
+ok(
+  !shouldApplyHydratedHistory(false, true, true, {
+    running: true,
+    live: { text: "partial" },
+    items: [],
+  }),
+  "running live stream without items is not replaced",
+);
+ok(
+  hasCachedLiveTurn({
+    running: true,
+    items: [{ kind: "assistant", streaming: true }],
+  }),
+  "streaming assistant counts as a cached live turn",
+);
+ok(
+  sameSessionPlaceholderItems("a.jsonl", { meta: { sessionPath: "b.jsonl" }, items: [{ kind: "user" }] }) === undefined,
+  "foreign session items are not placeholders",
+);
+ok(
+  (sameSessionPlaceholderItems("a.jsonl", { meta: { sessionPath: "a.jsonl" }, items: [{ kind: "user" }] }) ?? []).length === 1,
+  "same-session items stay placeholders",
+);
+
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);

desktop/frontend/src/__tests__/mermaid-rendering.test.tsx

@@ -205,6 +205,71 @@ console.log("\nmermaid rendering");
   eq(streamingCommitTarget("t\n\n$$\nx\n$$\nafter"), "t\n\n$$\nx\n$$\n", "closed display math promotes immediately");
   eq(streamingCommitTarget("para\n## Next sec"), "para\n", "a partial heading line completes the paragraph before it");
   eq(streamingCommitTarget("para\n## Done\ntail"), "para\n## Done\n", "a terminated heading promotes itself as a complete block");
+
+  const searchItem = (title: string, url: string) => `- **${title}**\n  <${url}>`;
+  const searchDump = [
+    searchItem("新闻本文", "https://example.com/a"),
+    searchItem("Bitcoin (BTC) Price", "https://example.com/b?utm_source=x"),
+    searchItem("KuCoin", "https://example.com/c"),
+  ].join("\n");
+  eq(
+    streamingCommitTarget(searchDump),
+    `${searchItem("新闻本文", "https://example.com/a")}\n${searchItem("Bitcoin (BTC) Price", "https://example.com/b?utm_source=x")}\n`,
+    "a later list marker commits prior tight list items, including indented URL continuations",
+  );
+  eq(
+    streamingCommitTarget(`${searchItem("新闻本文", "https://example.com/a")}\n- **Bit`),
+    `${searchItem("新闻本文", "https://example.com/a")}\n`,
+    "an in-progress list marker still commits the previous completed item",
+  );
+  eq(
+    streamingCommitTarget(searchItem("新闻本文", "https://example.com/a")),
+    "",
+    "a single list item stays in the tail until the next item or a blank line",
+  );
+  eq(
+    streamingCommitTarget("1. alpha\n2. beta\n3. gamma"),
+    "1. alpha\n2. beta\n",
+    "ordered list markers complete prior items the same way",
+  );
+  eq(
+    streamingCommitTarget("- [ ] one\n- [x] two\n- [ ] three"),
+    "- [ ] one\n- [x] two\n",
+    "task-list markers complete prior items the same way",
+  );
+  eq(
+    streamingCommitTarget("intro paragraph\n- first item\n  continued"),
+    "intro paragraph\n",
+    "a list marker completes the paragraph before it without taking the new item",
+  );
+  eq(
+    streamingCommitTarget("- parent\n  - child still typing"),
+    "- parent\n",
+    "a nested list marker completes the parent item and leaves the child in the tail",
+  );
+  eq(
+    streamingCommitTarget("not a heading\n---\nstill setext"),
+    "",
+    "a setext underline is not treated as a list marker",
+  );
+  eq(
+    streamingCommitTarget("*not-a-list*\nstill paragraph"),
+    "",
+    "emphasis without a marker space is not a list item",
+  );
+  eq(
+    streamingCommitTarget("t\n\n```\n- not a list\n- also not\n"),
+    "t\n\n```\n- not a list\n- also not\n",
+    "list markers inside an open fence do not create commit boundaries",
+  );
+  eq(
+    streamingCommitTarget("- one\n- two\n\n"),
+    "- one\n- two\n\n",
+    "a blank line after a list still commits the whole list",
+  );
+  const searchHtml = renderToStaticMarkup(<ReactMarkdown remarkPlugins={[]}>{searchDump}</ReactMarkdown>);
+  ok(searchHtml.includes("<ul>") && searchHtml.includes("<li>") && searchHtml.includes("新闻本文"),
+    "the search-list source still renders as a list in the final Markdown tree");
 }
 
 {
@@ -269,6 +334,25 @@ console.log("\nmermaid rendering");
   });
   eq(rootEl.textContent, "complete", "short stream finalization still commits immediately");
 
+  pendingFrame = undefined;
+  const firstSearch = "- **新闻本文**\n  <https://example.com/a>\n";
+  const secondSearch = `${firstSearch}- **Bitcoin**\n  <https://example.com/b>`;
+  await act(async () => {
+    root.render(<MarkdownTextProbe text={firstSearch} streaming />);
+    await flushTimers();
+  });
+  eq(rootEl.textContent, "", "a single tight list item stays off the parsed prefix");
+  await act(async () => {
+    root.render(<MarkdownTextProbe text={secondSearch} streaming />);
+    await new Promise((resolve) => setTimeout(resolve, 60));
+  });
+  const listFrame = pendingFrame;
+  await act(async () => {
+    listFrame?.(performance.now());
+    await flushTimers();
+  });
+  eq(rootEl.textContent, firstSearch, "a later list item commits the previous tight item into the parsed prefix");
+
   await act(async () => root.unmount());
   dom.window.close();
 }

desktop/frontend/src/__tests__/topic-activation.test.tsx

@@ -134,8 +134,9 @@ const checkpoints: CheckpointMeta[] = [];
 const tabA = tabMeta("tab-a", { active: true });
 const tabB = tabMeta("tab-b");
 const tabC = tabMeta("tab-c");
+const tabR = tabMeta("tab-r", { running: true, cancellable: true });
 let backendActiveId = "tab-a";
-const tabsById = new Map([tabA, tabB, tabC].map((tab) => [tab.id, tab]));
+const tabsById = new Map([tabA, tabB, tabC, tabR].map((tab) => [tab.id, tab]));
 const eventHandlers: Array<(e: WireEvent) => void> = [];
 const readyHandlers: Array<(tabId?: string) => void> = [];
 const topicActivationHandlers: Array<(e: TopicActivationEvent) => void> = [];
@@ -151,6 +152,7 @@ function emitActivation(event: TopicActivationEvent): void {
 }
 
 function historyFor(tabID: string): HistoryMessage[] {
+  if (tabID === "tab-r") return [{ role: "user", content: "帮我查询，现在我链接的 deep" }];
   return [{ role: "user", content: `history ${tabID}` }];
 }
 
@@ -297,6 +299,55 @@ await act(async () => {
 });
 eq(controller?.state.meta?.gitBranch, "feature/x", "tab:meta for a different session binding is discarded");
 
+// ── switch away from a thinking session and back: keep its transcript ──────
+await act(async () => {
+  await controller?.activateTopic("project", tabR.workspaceRoot, tabR.topicId ?? "");
+  await flushPromises();
+});
+await act(async () => {
+  emitActivation({ requestId: requestIdByTab.get("tab-r") ?? "", tabId: "tab-r", phase: "ready" });
+  await flushPromises();
+});
+await waitFor("running session hydrates on first open", () =>
+  controller?.activeTabId === "tab-r" &&
+  (controller.state.items.some((item) => item.kind === "user" && item.text === "帮我查询，现在我链接的 deep") ?? false),
+);
+eq(controller?.state.running, true, "reattached thinking session stays marked running");
+eq(controller?.state.hydrating, false, "running-session hydrate settles instead of leaving Welcome");
+
+await act(async () => {
+  await controller?.activateTopic("project", tabB.workspaceRoot, tabB.topicId ?? "");
+  await flushPromises();
+});
+await act(async () => {
+  emitActivation({ requestId: requestIdByTab.get("tab-b") ?? "", tabId: "tab-b", phase: "ready" });
+  await flushPromises();
+});
+await waitFor("idle session replaces the thinking surface", () => hasHistory("tab-b") && controller?.state.hydrating === false);
+
+await act(async () => {
+  await controller?.activateTopic("project", tabR.workspaceRoot, tabR.topicId ?? "");
+  await flushPromises();
+});
+eq(controller?.activeTabId, "tab-r", "switch-back selects the thinking session");
+eq(
+  controller?.state.hydratePlaceholderItems?.some((item) => item.kind === "user" && item.text === "history tab-b") ?? false,
+  false,
+  "switch-back does not present the other session as a hydration placeholder",
+);
+await act(async () => {
+  emitActivation({ requestId: requestIdByTab.get("tab-r") ?? "", tabId: "tab-r", phase: "ready" });
+  await flushPromises();
+});
+await waitFor("switch-back restores the thinking transcript", () =>
+  controller?.activeTabId === "tab-r" &&
+  controller.state.hydrating === false &&
+  (controller.state.items.some((item) => item.kind === "user" && item.text === "帮我查询，现在我链接的 deep") ?? false),
+);
+eq(controller?.state.running, true, "switch-back keeps the composer in the live turn");
+eq(controller?.state.items.some((item) => item.kind === "user" && item.text === "history tab-b") ?? false, false, "switch-back does not keep the other session as the visible transcript");
+eq(controller?.state.hydratePlaceholderItems?.length ?? 0, 0, "switch-back clears the foreign placeholder after live history lands");
+
 await act(async () => {
   root.unmount();
 });

desktop/frontend/src/__tests__/transcript-virtualization.test.tsx

@@ -248,5 +248,31 @@ function firstTextNode(root: Node): Text | null {
   }
 }
 
+// ── Short transcripts must not clone the first user bubble at the top ────────
+// Virtuoso alignToBottom uses margin-top:auto to pin short lists to the
+// composer. Combined with firstItemIndex it also paints a second copy of the
+// first user row at the scroller top, leaving a large empty band in between.
+{
+  const harness = await createTranscriptHarness({ viewportHeight: 600, rowHeight: 80 });
+  try {
+    await harness.render(
+      [
+        { kind: "user", id: "u-short", text: "你好" },
+        { kind: "assistant", id: "a-short", text: "hello", reasoning: "", streaming: false },
+      ],
+      { running: false },
+    );
+    await harness.settle();
+    const users = harness.container.querySelectorAll(".msg--user");
+    ok(users.length === 1, `a one-turn transcript mounts the user bubble once (got ${users.length})`);
+    const list = harness.container.querySelector<HTMLElement>('[data-testid="virtuoso-item-list"]');
+    ok(list != null, "short transcript mounts the Virtuoso item list");
+    ok(list?.style.marginTop !== "auto", `short content is not bottom-shifted (marginTop=${JSON.stringify(list?.style.marginTop ?? null)})`);
+  } finally {
+    await harness.unmount();
+    await harness.close();
+  }
+}
+
 console.log(`\n${passed} passed, ${failed} failed`);
 if (failed > 0) process.exit(1);

desktop/frontend/src/__tests__/typography-overflow-contract.test.ts

@@ -3,6 +3,7 @@
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { JSDOM } from "jsdom";
 import { TEXT_SIZES } from "../lib/textSize";
 
 const testDir = dirname(fileURLToPath(import.meta.url));
@@ -98,6 +99,69 @@ eq(
 );
 eq(finalDeclaration(".transcript--empty", "overflow-y"), "auto", "empty transcript can scroll instead of clipping");
 eq(finalDeclaration(".welcome", "overflow"), "visible", "welcome empty state is not clipped by its own box");
+ok(
+  /\.md\s*>\s*:where\([^)]*p[^)]*ul[^)]*ol[^)]*\)\s*\{[^}]*content-visibility:\s*auto;[^}]*contain-intrinsic-size:\s*auto 72px;/.test(styles),
+  "non-transcript markdown still culls offscreen blocks with a 72px placeholder",
+);
+ok(
+  /\.transcript__row\s+\.md\s*>\s*\*\s*(?:,[^{]*)?\{[^}]*content-visibility:\s*visible;[^}]*contain-intrinsic-size:\s*none;/.test(styles),
+  "virtual transcript rows do not measure markdown through 72px placeholders",
+);
+ok(
+  hasDeclaration(".transcript__row .msg", "content-visibility", "visible") &&
+    hasDeclaration(".transcript__row .turn-collapse", "content-visibility", "visible"),
+  "virtual transcript cards stay measurable after the markdown override",
+);
+
+function paddingSides(value: string) {
+  const parts = value.trim().split(/\s+/);
+  if (parts.length === 1) return { right: parts[0], left: parts[0] };
+  if (parts.length === 2 || parts.length === 3) return { right: parts[1], left: parts[1] };
+  return { right: parts[1], left: parts[3] };
+}
+function isZeroPad(value: string | undefined) {
+  return value === undefined || value === "0" || value === "0px";
+}
+for (const block of matchingBlocks(".transcript")) {
+  const shorthand = /(?:^|;)\s*padding\s*:\s*([^;]+)/.exec(block);
+  if (shorthand) {
+    const sides = paddingSides(shorthand[1]);
+    ok(
+      isZeroPad(sides.left) && isZeroPad(sides.right),
+      `Virtuoso scroller padding stays vertical-only (${shorthand[1].trim()})`,
+    );
+  }
+  const padLeft = /(?:^|;)\s*padding-left\s*:\s*([^;]+)/.exec(block);
+  const padRight = /(?:^|;)\s*padding-right\s*:\s*([^;]+)/.exec(block);
+  ok(isZeroPad(padLeft?.[1].trim()), "Virtuoso scroller does not set padding-left");
+  ok(isZeroPad(padRight?.[1].trim()), "Virtuoso scroller does not set padding-right");
+}
+ok(hasDeclaration(".transcript", "--transcript-inline-pad", "32px"), "default transcript inline inset is 32px");
+ok(hasDeclaration(".transcript", "--transcript-inline-pad", "16px"), "narrow viewports tighten the transcript inline inset");
+eq(finalDeclaration(".transcript__row", "padding-left"), "var(--transcript-inline-pad, 32px)", "virtual rows own the left inset");
+eq(finalDeclaration(".transcript__row", "padding-right"), "var(--transcript-inline-pad, 32px)", "virtual rows own the right inset");
+eq(finalDeclaration(".transcript__header", "padding-left"), "var(--transcript-inline-pad, 32px)", "load-older header uses the same inline inset");
+eq(finalDeclaration(".transcript--empty", "padding"), "16px 32px", "empty transcript keeps its own horizontal inset");
+
+{
+  const stylesheet = readFileSync(resolve(testDir, "../styles.css"), "utf8");
+  const dom = new JSDOM(
+    `<!doctype html><html><head><style>${stylesheet}</style></head><body>
+      <div class="transcript__row"><div class="md"><p id="inside">inside</p></div></div>
+      <div class="md"><p id="outside">outside</p></div>
+    </body></html>`,
+    { pretendToBeVisual: true },
+  );
+  const inside = dom.window.getComputedStyle(dom.window.document.getElementById("inside")!);
+  const outside = dom.window.getComputedStyle(dom.window.document.getElementById("outside")!);
+  // jsdom may not implement content-visibility; treat an empty computed value
+  // as "engine gap" and still require the source contract above.
+  if (inside.contentVisibility || outside.contentVisibility) {
+    eq(inside.contentVisibility, "visible", "computed style keeps transcript markdown measurable");
+    eq(outside.contentVisibility, "auto", "computed style still culls markdown outside the transcript");
+  }
+  dom.window.close();
+}
 ok(
   hasDeclaration(".transcript--empty > .welcome", "margin-block", "auto"),
   "empty-state auto margins apply only to the welcome content",

desktop/frontend/src/__tests__/use-controller-meta.test.ts

@@ -201,22 +201,22 @@ console.log("\nuse controller meta");
   );
   eq(
     localizedBackendNoticeText("session changed on disk; unsaved local transcript was saved as recovery branch 20260706-152144.863947300-longcat-openai-LongCat-2.0-119b7259f151-recovery-693ce51bcbcbaa9"),
-    "The session changed on disk, so the unsaved local transcript was kept as a conflict copy.",
+    "The session changed on disk, so the unsaved local transcript was kept as another saved version.",
     "legacy recovery branch notice can be normalized without exposing internal branch id",
   );
   eq(
     localizedBackendNoticeText("session changed on disk; unsaved local transcript was saved as a conflict copy"),
-    "The session changed on disk, so the unsaved local transcript was kept as a conflict copy.",
+    "The session changed on disk, so the unsaved local transcript was kept as another saved version.",
     "recovery copy notice can be normalized",
   );
   eq(
     localizedBackendNoticeText("session conflicts kept recurring; kept the transcript on the current recovery branch"),
-    "Repeated save conflicts were detected, so the current conflict copy was saved in an isolated recovery branch.",
+    "Repeated save conflicts were detected, so the current version was saved separately.",
     "legacy repeated recovery conflict notice can be normalized",
   );
   eq(
     localizedBackendNoticeText("repeated save conflicts were detected; saved the current conflict copy in place"),
-    "Repeated save conflicts were detected, so the current conflict copy was saved in an isolated recovery branch.",
+    "Repeated save conflicts were detected, so the current version was saved separately.",
     "repeated recovery conflict notice can be normalized",
   );
   eq(
@@ -264,7 +264,7 @@ console.log("\nuse controller meta");
   );
   eq(
     localizedNoticeText("reworded recovery copy", "session_recovery_forked"),
-    "The session changed on disk, so the unsaved local transcript was kept as a conflict copy.",
+    "The session changed on disk, so the unsaved local transcript was kept as another saved version.",
     "session recovery fork localization uses its stable notice code",
   );
   eq(
@@ -274,7 +274,7 @@ console.log("\nuse controller meta");
   );
   eq(
     localizedNoticeText("reworded depth cap", "session_recovery_depth_cap"),
-    "Repeated save conflicts were detected, so the current conflict copy was saved in an isolated recovery branch.",
+    "Repeated save conflicts were detected, so the current version was saved separately.",
     "session recovery depth-cap localization uses its stable notice code",
   );
   eq(

desktop/frontend/src/components/HistoryPanel.tsx

@@ -1,10 +1,10 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type { MouseEvent as ReactMouseEvent } from "react";
-import { Archive, Pencil, Search, Trash2, RotateCcw } from "lucide-react";
+import { Archive, GitBranch, Pencil, Search, Trash2, RotateCcw } from "lucide-react";
 import { app } from "../lib/bridge";
 import { t, useT } from "../lib/i18n";
 import { historySessionDisplayTitle, sessionActivityTime } from "../lib/session";
-import type { HistoryMessage, HistorySearchContextLine, HistorySearchHit, SessionMeta } from "../lib/types";
+import type { HistoryMessage, HistorySearchContextLine, HistorySearchHit, RecoveryLineageView, SessionMeta } from "../lib/types";
 import { historyMessagesToItems, type Item } from "../lib/useController";
 import { useHistoryCatalog } from "../lib/useHistoryCatalog";
 import { Transcript } from "./Transcript";
@@ -12,6 +12,8 @@ import { ContextMenu, contextMenuPointFromEvent, type ContextMenuItem, type Cont
 import { useDeferredClose } from "../lib/useMountTransition";
 import { ModalCloseButton } from "./ModalCloseButton";
 import { HistoryFilterSelect } from "./HistoryFilterSelect";
+import { RecoveryLineageDialog } from "./RecoveryLineageDialog";
+import { useToast } from "../lib/toast";
 
 type HistoryScopeFilter = "all" | "project" | "global";
 type HistoryStatusFilter = "all" | "current" | "open";
@@ -50,9 +52,14 @@ export function HistoryPanel({
   onClose: () => void;
 }) {
   const tr = useT();
+  const { showToast } = useToast();
   const isTrash = kind === "trash";
   // Play the modal exit animation, then let the parent unmount us.
   const { status, requestClose } = useDeferredClose(onClose, 240);
+  const [savedVersions, setSavedVersions] = useState<{
+    topic: { scope: string; workspaceRoot?: string; topicId: string };
+    view: RecoveryLineageView;
+  } | null>(null);
   const [editing, setEditing] = useState<string | null>(null);
   const [draft, setDraft] = useState("");
   const [query, setQuery] = useState("");
@@ -321,6 +328,16 @@ export function HistoryPanel({
               startRename(target);
             },
           },
+          ...(menuSession.topicId
+            ? [
+                {
+                  key: "other-saved-versions",
+                  icon: <GitBranch size={13} />,
+                  label: tr("recovery.inspectLineage"),
+                  onSelect: () => void inspectOtherSavedVersions(menuSession),
+                } as ContextMenuItem,
+              ]
+            : []),
           ...(menuSession.current
             ? []
             : [
@@ -396,6 +413,21 @@ export function HistoryPanel({
     if (!selectedSession || running || isTrash) return;
     onResume(selectedSession);
   };
+  const inspectOtherSavedVersions = async (session: SessionMeta) => {
+    if (isTrash || !session.topicId) return;
+    closeHistoryMenus();
+    try {
+      const topic = {
+        scope: session.scope || "global",
+        workspaceRoot: session.workspaceRoot || undefined,
+        topicId: session.topicId,
+      };
+      const view = await app.GetRecoveryLineage(topic);
+      setSavedVersions({ topic, view });
+    } catch (err) {
+      showToast(err instanceof Error ? err.message : String(err), "error");
+    }
+  };
   const renameSelected = () => {
     if (!selectedSession || running || isTrash) return;
     closeHistoryMenus();
@@ -684,6 +716,16 @@ export function HistoryPanel({
                       <button className="btn btn--small" type="button" disabled={!selectedSession || running} onClick={renameSelected}>
                         {tr("history.rename")}
                       </button>
+                      {selectedSession?.topicId && (
+                        <button
+                          className="btn btn--small"
+                          type="button"
+                          disabled={!selectedSession}
+                          onClick={() => void inspectOtherSavedVersions(selectedSession)}
+                        >
+                          <GitBranch size={13} /> {tr("recovery.inspectLineage")}
+                        </button>
+                      )}
                       <button
                         className="btn btn--small btn--danger"
                         type="button"
@@ -727,6 +769,35 @@ export function HistoryPanel({
           ariaLabel={tr("history.trashActions")}
           onClose={closeHistoryMenus}
         />
+        {savedVersions && (
+          <RecoveryLineageDialog
+            topic={savedVersions.topic}
+            initial={savedVersions.view}
+            onClose={() => setSavedVersions(null)}
+            onChanged={async () => {
+              const view = await app.GetRecoveryLineage(savedVersions.topic);
+              setSavedVersions({ topic: savedVersions.topic, view });
+            }}
+            onOpenVersion={async (path) => {
+              const session = sessions.find((item) => item.path === path) ?? {
+                path,
+                preview: "",
+                turns: 0,
+                turnsState: "unknown",
+                createdAt: 0,
+                lastActivityAt: 0,
+                modTime: 0,
+                current: false,
+                open: false,
+                scope: savedVersions.topic.scope,
+                workspaceRoot: savedVersions.topic.workspaceRoot,
+                topicId: savedVersions.topic.topicId,
+                recovered: true,
+              };
+              onResume(session);
+            }}
+          />
+        )}
       </div>
       </section>
     </div>

desktop/frontend/src/components/Markdown.tsx

@@ -131,12 +131,15 @@ export function streamingMarkdownCommitInterval(textLength: number): number {
   return 50;
 }
 
-// streamingCommitTarget returns the prefix worth parsing while a stream is
-// live: everything up to the last completed block — a blank line, a closed
-// fence, closed display math, or the start of a heading, all on terminated
-// lines. The in-progress block rides the plain-text tail instead, so Markdown
-// re-parses once per completed block rather than once per commit interval. An
-// unclosed fence or $$ keeps the whole text parsed for live code highlighting.
+const STREAMING_LIST_ITEM_RE = /^ {0,3}(?:[*+-]|\d{1,9}[.)])(?:[ \t]+|$)/;
+const STREAMING_THEMATIC_BREAK_RE = /^ {0,3}(?:(?:-[ \t]*){3,}|(?:\*[ \t]*){3,}|(?:_[ \t]*){3,})[ \t]*$/;
+
+function isStreamingListItemLine(line: string): boolean {
+  return STREAMING_LIST_ITEM_RE.test(line) && !STREAMING_THEMATIC_BREAK_RE.test(line);
+}
+
+// Live parse prefix: last completed block. A later list marker commits prior
+// items only — the new item stays in the tail so indented continuations can join.
 export function streamingCommitTarget(text: string): string {
   let lineStart = 0;
   let fence: { marker: string; length: number } | null = null;
@@ -165,6 +168,7 @@ export function streamingCommitTarget(text: string): string {
       // A heading interrupts a paragraph, so a partial heading line already
       // completes everything before it; a terminated one is itself complete.
       else if (/^ {0,3}#{1,6}[ \t]+/.test(line)) boundary = terminated ? lineEnd : lineStart;
+      else if (isStreamingListItemLine(line)) boundary = lineStart;
     }
     lineStart = lineEnd;
   }

desktop/frontend/src/components/ProjectTree.tsx

@@ -1172,7 +1172,7 @@ export function ProjectTree({
       const accentStyle = projectAccentStyle(node.projectColor, scope === "global" ? "var(--project-tree-global-accent)" : undefined);
       const active = topicIsActive(node, activeScope, activeWorkspaceRoot, activeTopicId, activeSessionPath);
       const label = (node.label || node.topicId || "Untitled").replace(/^●\s*/, "");
-      const conflictCopyLabel = isSessionNode && node.recovered ? t("recovery.badge") : "";
+      // Ordinary list never advertises recovery copies; History owns that view.
       const activityAt = node.lastActivityAt || node.createdAt || 0;
       // Every variant is a single-line row with the activity time on the right;
       // classic moved there too so turns and the exact date live in the hover
@@ -1198,8 +1198,7 @@ export function ProjectTree({
       const imSourceLabel = imSource?.label || "";
       const imSourceTitle = imSourceLabel ? t("msg.fromIm", { source: imSourceLabel }) : "";
       const imSourcePlatform = (imSource?.platform || "im").replace(/[^a-z0-9_-]/gi, "").toLowerCase() || "im";
-      const conflictCopyTitle = isSessionNode && node.recovered ? t("recovery.branch") : "";
-      const title = [label, conflictCopyTitle, imSourceTitle, statusLabel, metaFull, projectTreeDedupedExactTime(metaFull, exactTimeLabel)].filter(Boolean).join(" · ");
+      const title = [label, imSourceTitle, statusLabel, metaFull, projectTreeDedupedExactTime(metaFull, exactTimeLabel)].filter(Boolean).join(" · ");
       const topicMenuOpen = !isSessionNode && menuTopic === topicId;
       const pinned = Boolean(node.pinned);
       const pinLabel = t(pinned ? "projectTree.unpinTopic" : "projectTree.pinTopic");
@@ -1323,7 +1322,7 @@ export function ProjectTree({
           >
             <span className="project-tree__topic-copy">
               <span className="project-tree__topic-heading">
-                <span className="project-tree__topic-label">{conflictCopyLabel ? `${label} · ${conflictCopyLabel}` : label}</span>
+                <span className="project-tree__topic-label">{label}</span>
                 {imSource && (
                   <span
                     className={`project-tree__topic-im project-tree__topic-im--${imSourcePlatform}`}

desktop/frontend/src/components/RecoveryLineageDialog.tsx

@@ -0,0 +1,144 @@
+import { useState } from "react";
+import { createPortal } from "react-dom";
+import { GitBranch, Trash2, X } from "lucide-react";
+import { app } from "../lib/bridge";
+import { asArray } from "../lib/array";
+import type { ProjectTopicKey } from "../lib/sessionCatalogTypes";
+import type { RecoveryCleanupResult, RecoveryLineageView } from "../lib/types";
+import { useT } from "../lib/i18n";
+
+interface RecoveryLineageDialogProps {
+  topic: ProjectTopicKey;
+  initial: RecoveryLineageView;
+  onClose: () => void;
+  onChanged: () => Promise<void> | void;
+  onOpenVersion?: (path: string) => Promise<void> | void;
+}
+
+function fileName(path: string): string {
+  const parts = path.split(/[\\/]/);
+  return parts[parts.length - 1] || path;
+}
+
+function roleKey(role: string): "recovery.role.covered_copy" | "recovery.role.adopted" | "recovery.role.preferred" | "recovery.role.diverged" | "recovery.role.normal" {
+  if (role === "covered_copy") return "recovery.role.covered_copy";
+  if (role === "adopted") return "recovery.role.adopted";
+  if (role === "preferred") return "recovery.role.preferred";
+  if (role === "diverged") return "recovery.role.diverged";
+  return "recovery.role.normal";
+}
+
+export function RecoveryLineageDialog({ topic, initial, onClose, onChanged, onOpenVersion }: RecoveryLineageDialogProps) {
+  const t = useT();
+  const [view, setView] = useState(initial);
+  const [preview, setPreview] = useState<RecoveryCleanupResult | null>(null);
+  const [busy, setBusy] = useState(false);
+  const [result, setResult] = useState<RecoveryCleanupResult | null>(null);
+
+  const choose = async (path: string) => {
+    if (busy) return;
+    setBusy(true);
+    try {
+      await app.ChooseRecoveryBranch({ ...topic, path });
+      setView(await app.GetRecoveryLineage(topic));
+      await onChanged();
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const openVersion = async (path: string) => {
+    if (busy || !onOpenVersion) return;
+    setBusy(true);
+    try {
+      await onOpenVersion(path);
+      onClose();
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const clean = async (apply: boolean) => {
+    if (busy) return;
+    setBusy(true);
+    try {
+      const next = await app.CleanRecoveryLineage({ ...topic, apply });
+      if (!apply) {
+        setPreview(next);
+        return;
+      }
+      setResult(next);
+      setPreview(null);
+      setView(await app.GetRecoveryLineage(topic));
+      await onChanged();
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return createPortal(
+    <div className="management-modal-backdrop recovery-lineage-backdrop" onMouseDown={(event) => { if (event.target === event.currentTarget) onClose(); }}>
+      <section className="management-modal recovery-lineage-dialog" role="dialog" aria-modal="true" aria-labelledby="recovery-lineage-title">
+        <header className="management-modal__head">
+          <div>
+            <div className="management-modal__title" id="recovery-lineage-title">
+              <GitBranch size={17} aria-hidden="true" /> {t("recovery.lineageTitle")}
+            </div>
+            <div className="management-modal__summary">
+              {t("recovery.lineageSummary", { branches: view.branchCount, unresolved: view.unresolved })}
+            </div>
+          </div>
+          <button type="button" className="icon-btn" onClick={onClose} aria-label={t("common.close")}><X size={16} /></button>
+        </header>
+        <div className="recovery-lineage-dialog__body">
+          {asArray(view.members).map((member) => (
+            <div className="recovery-lineage-dialog__member" key={member.path}>
+              <div className="recovery-lineage-dialog__member-name" title={member.path}>{fileName(member.path)}</div>
+              <div className="recovery-lineage-dialog__member-meta">
+                <span>{t(roleKey(member.role))}</span>
+                <span>{t(member.turns === 1 ? "history.turnOne" : "history.turnOther", { n: member.turns })}</span>
+                {(member.open || member.running) && <span>{t("recovery.inUse")}</span>}
+                {member.canonical && <span>{t("recovery.role.preferred")}</span>}
+                {onOpenVersion && (
+                  <button type="button" className="recovery-lineage-dialog__choose" disabled={busy} onClick={() => void openVersion(member.path)}>
+                    {t("recovery.openVersion")}
+                  </button>
+                )}
+                {member.role !== "covered_copy" && !member.canonical && (
+                  <button type="button" className="recovery-lineage-dialog__choose" disabled={busy} onClick={() => void choose(member.path)}>
+                    {t("recovery.chooseBranch")}
+                  </button>
+                )}
+              </div>
+            </div>
+          ))}
+          {view.members.length === 0 && <div className="management-modal__summary">{t("recovery.lineageEmpty")}</div>}
+          {preview && (
+            <div className="recovery-lineage-dialog__notice" role="status">
+              {t("recovery.cleanupConfirm", { count: preview.eligible })}
+            </div>
+          )}
+          {result && (
+            <div className="recovery-lineage-dialog__notice" role="status">
+              {t("recovery.cleanupResult", { moved: result.moved, busy: result.busy, kept: result.kept })}
+            </div>
+          )}
+        </div>
+        <footer className="modal__actions recovery-lineage-dialog__actions">
+          <button type="button" className="btn" onClick={onClose}>{t("common.close")}</button>
+          {view.cleanupEligible > 0 && !preview && (
+            <button type="button" className="btn" disabled={busy} onClick={() => void clean(false)}>
+              <Trash2 size={14} /> {t("recovery.previewCleanup")}
+            </button>
+          )}
+          {preview && preview.eligible > 0 && (
+            <button type="button" className="btn btn--danger" disabled={busy} onClick={() => void clean(true)}>
+              <Trash2 size={14} /> {t("recovery.applyCleanup")}
+            </button>
+          )}
+        </footer>
+      </section>
+    </div>,
+    document.body,
+  );
+}

desktop/frontend/src/components/Transcript.tsx

@@ -721,7 +721,9 @@ export function Transcript({
             components={hasOlderHistory ? TRANSCRIPT_VIRTUOSO_COMPONENTS_WITH_HEADER : TRANSCRIPT_VIRTUOSO_COMPONENTS}
             computeItemKey={(_index, row) => `${tabId ?? ""}:${String(row.key)}`}
             firstItemIndex={firstItemIndex}
-            alignToBottom
+            // Do not set alignToBottom: Virtuoso's margin-top:auto plus
+            // firstItemIndex paints a ghost first-user bubble and empty band
+            // in short chats. Tail pin stays followOutput + scrollToBottom.
             followOutput={(atBottom) => atBottom ? "auto" : false}
             atBottomThreshold={TRANSCRIPT_AT_BOTTOM_THRESHOLD_PX}
             atBottomStateChange={atBottomStateChange}

desktop/frontend/src/lib/bridge.ts

@@ -84,6 +84,9 @@ import type {
   PluginInstallOptions,
   PluginView,
   ProjectNode,
+  RecoveryLineageView,
+  RecoveryCleanupRequest,
+  RecoveryCleanupResult,
   SessionCatalogBindings,
   PromptHistoryEntry,
   PromptHistoryResult,
@@ -315,6 +318,9 @@ export interface AppBindings extends SessionCatalogBindings, HistoryCatalogBindi
   PreviewSession(path: string): Promise<HistoryMessage[]>;
   DeleteSession(path: string): Promise<void>;
   DeleteRecoveryCopy(path: string): Promise<void>;
+  GetRecoveryLineage(key: { scope: string; workspaceRoot?: string; topicId: string }): Promise<RecoveryLineageView>;
+  ChooseRecoveryBranch(request: import("./types").RecoveryPreferenceRequest): Promise<void>;
+  CleanRecoveryLineage(request: RecoveryCleanupRequest): Promise<RecoveryCleanupResult>;
   RestoreSession(path: string): Promise<void>;
   PurgeTrashedSession(path: string): Promise<void>;
   PurgeRecoveryCopy(path: string): Promise<void>;
@@ -1235,7 +1241,7 @@ const mockVercelModels = ["anthropic/claude-sonnet-4.6", "anthropic/claude-opus-
 const mockOllamaCloudModels = ["glm-5.2", "kimi-k2.7-code", "deepseek-v4-pro", "deepseek-v4-flash", "minimax-m3", "nemotron-3-nano:30b", "qwen3-coder-next"];
 
 const mockProviderPresetTemplates: MockProviderPresetTemplate[] = [
-  mockPreset("deepseek-responses", "DeepSeek Official Responses API", "Official stateless DeepSeek Responses API for Flash with server-side web search.", "DEEPSEEK_API_KEY", mockProviderTemplate({ name: "deepseek-responses", kind: "responses", baseUrl: "https://api.deepseek.com", models: ["deepseek-v4-flash"], default: "deepseek-v4-flash", apiKeyEnv: "DEEPSEEK_API_KEY", balanceUrl: "https://api.deepseek.com/user/balance", webSearch: true, serverWebSearchCapability: true, contextWindow: 1000000, supportedEfforts: ["low", "high", "max"], defaultEffort: "high" })),
+  mockPreset("deepseek-responses", "DeepSeek Official Responses API", "Official stateless DeepSeek Responses API for Flash and Pro with server-side web search.", "DEEPSEEK_API_KEY", mockProviderTemplate({ name: "deepseek-responses", kind: "responses", baseUrl: "https://api.deepseek.com", models: ["deepseek-v4-flash", "deepseek-v4-pro"], default: "deepseek-v4-flash", apiKeyEnv: "DEEPSEEK_API_KEY", balanceUrl: "https://api.deepseek.com/user/balance", webSearch: true, serverWebSearchCapability: true, contextWindow: 1000000, modelOverrides: [{ model: "deepseek-v4-flash", reasoningProtocol: "", supportedEfforts: ["disabled", "low", "high", "max"], defaultEffort: "high" }, { model: "deepseek-v4-pro", reasoningProtocol: "", supportedEfforts: ["disabled", "high", "max"], defaultEffort: "high" }] })),
   mockPreset("longcat-openai", "LongCat OpenAI", "LongCat Platform OpenAI-compatible endpoint for LongCat-2.0.", "LONGCAT_API_KEY", mockProviderTemplate({ name: "longcat-openai", kind: "openai", baseUrl: "https://api.longcat.chat/openai/v1", modelsUrl: "https://api.longcat.chat/openai/v1/models", models: mockLongCatModels, default: "LongCat-2.0", apiKeyEnv: "LONGCAT_API_KEY", contextWindow: 131072, thinking: "enabled", supportedEfforts: ["enabled", "disabled"], defaultEffort: "enabled" })),
   mockPreset("longcat-anthropic", "LongCat Anthropic", "LongCat Platform Anthropic-compatible Messages endpoint for LongCat-2.0.", "LONGCAT_API_KEY", mockProviderTemplate({ name: "longcat-anthropic", kind: "anthropic", baseUrl: "https://api.longcat.chat/anthropic", modelsUrl: "https://api.longcat.chat/anthropic/v1/models", models: mockLongCatModels, default: "LongCat-2.0", apiKeyEnv: "LONGCAT_API_KEY", authHeader: true, contextWindow: 131072, thinking: "enabled", supportedEfforts: ["enabled", "disabled"], defaultEffort: "enabled" })),
   mockPreset("token-rhythm", "Token Rhythm", "Token Rhythm (基元律动) multi-model OpenAI-compatible gateway.", "TOKEN_RHYTHM_API_KEY", mockProviderTemplate({ name: "token-rhythm", kind: "openai", baseUrl: "https://tokenrhythm.studio/v1", modelsUrl: "https://tokenrhythm.studio/v1/models", models: mockTokenRhythmModels, visionModels: ["kimi-k2.5", "kimi-k2.6", "kimi-k2.7-code"], default: "deepseek-v4-flash", apiKeyEnv: "TOKEN_RHYTHM_API_KEY", contextWindow: 1000000, modelOverrides: mockTokenRhythmModelOverrides })),
@@ -3324,6 +3330,24 @@ function makeMockApp(): AppBindings {
     async DeleteRecoveryCopy(path: string) {
       return this.DeleteSession(path);
     },
+    async GetRecoveryLineage(key) {
+      const topic = findMockTopic(key.topicId);
+      return {
+        groupId: key.topicId,
+        state: topic?.recoveryState ?? "normal",
+        branchCount: topic?.recoveryBranchCount ?? 0,
+        unresolved: topic?.recoveryUnresolvedCount ?? 0,
+        cleanupEligible: topic?.recoveryCleanupEligibleCount ?? 0,
+        members: [],
+      };
+    },
+    async ChooseRecoveryBranch() {},
+    async CleanRecoveryLineage(request) {
+      const topic = findMockTopic(request.topicId);
+      const eligible = topic?.recoveryCleanupEligibleCount ?? 0;
+      if (request.apply && topic) topic.recoveryCleanupEligibleCount = 0;
+      return { eligible, moved: request.apply ? eligible : 0, busy: 0, kept: 0, dryRun: !request.apply, items: [] };
+    },
     async RestoreSession(path: string) {
       const i = trashedSessions.findIndex((s) => s.path === path);
       if (i >= 0) {

desktop/frontend/src/lib/hydrateHistoryApply.ts

@@ -0,0 +1,41 @@
+/** Live-turn markers that a lagging history snapshot must not replace. */
+export type HydrateLiveState = {
+  running?: boolean;
+  turnActive?: boolean;
+  live?: unknown;
+  currentAssistant?: unknown;
+  pendingUser?: unknown;
+  items: ReadonlyArray<{ kind: string; streaming?: boolean; status?: string }>;
+};
+
+export function hasCachedLiveTurn(state: HydrateLiveState | undefined): boolean {
+  if (!state?.running && !state?.turnActive) return false;
+  if (state.live || state.currentAssistant || state.pendingUser !== undefined) return true;
+  return state.items.some((item) =>
+    (item.kind === "assistant" && item.streaming) ||
+    (item.kind === "tool" && item.status === "running"),
+  );
+}
+
+// Skip replace when a live transcript is already on screen; an empty
+// surface still has to apply history or switch-back shows Welcome.
+export function shouldApplyHydratedHistory(
+  skipHistory: boolean,
+  hasProjection: boolean,
+  foregroundTurnActive: boolean,
+  state: HydrateLiveState | undefined,
+): boolean {
+  if (skipHistory || !hasProjection) return false;
+  if (!foregroundTurnActive) return true;
+  return (state?.items.length ?? 0) === 0 && !hasCachedLiveTurn(state);
+}
+
+export function sameSessionPlaceholderItems<T>(
+  targetSessionPath: string | undefined,
+  prev: { meta?: { sessionPath?: string }; items?: T[] } | undefined,
+): T[] | undefined {
+  const target = (targetSessionPath ?? "").trim();
+  const current = (prev?.meta?.sessionPath ?? "").trim();
+  if (!target || !current || target !== current) return undefined;
+  return prev?.items;
+}

desktop/frontend/src/lib/projectTreeTopic.ts

@@ -180,13 +180,12 @@ export function normalizeTopicStatus(status?: string): ProjectTopicStatus | "" {
 }
 
 export function topicStatus(node: ProjectNode): ProjectTopicStatus | "" {
-  // Active runtime states take priority over the informational diverged-recovery
-  // marker so a topic that is simultaneously running and has unresolved branches
-  // surfaces the live state first.
+  // Ordinary list never surfaces recovery-branch status. Active runtime states
+  // only: thinking/streaming/waiting/etc. History owns other saved versions.
   const live = node.running ? "streaming" : "";
   const stored = normalizeTopicStatus(node.status);
   if (stored && stored !== "diverged_recovery") return stored;
-  return live || stored;
+  return live;
 }
 
 export function projectTreeTopicArchiveBlocked(node: ProjectNode): boolean {

desktop/frontend/src/lib/types.ts

@@ -512,10 +512,61 @@ export interface ProjectNode {
   recoveryReason?: string;
   recoveryDigest?: string;
   recoveryParentId?: string;
+  recoveryState?: "normal" | "repairing" | "adopted" | "preferred" | "diverged" | "recovery_only" | string;
+  recoveryBranchCount?: number;
+  recoveryUnresolvedCount?: number;
+  recoveryCleanupEligibleCount?: number;
   isolatedWorktree?: boolean;
   children?: ProjectNode[];
 }
 
+export interface RecoveryLineageMember {
+  path: string;
+  role: "normal" | "covered_copy" | "adopted" | "preferred" | "diverged" | string;
+  canonical: boolean;
+  turns: number;
+  open: boolean;
+  running: boolean;
+}
+
+export interface RecoveryLineageView {
+  groupId: string;
+  state: string;
+  branchCount: number;
+  unresolved: number;
+  cleanupEligible: number;
+  members: RecoveryLineageMember[];
+}
+
+export interface RecoveryCleanupRequest {
+  scope: string;
+  workspaceRoot?: string;
+  topicId: string;
+  apply: boolean;
+}
+
+export interface RecoveryPreferenceRequest {
+  scope: string;
+  workspaceRoot?: string;
+  topicId: string;
+  path: string;
+}
+
+export interface RecoveryCleanupItem {
+  path: string;
+  status: "eligible" | "moved" | "busy" | "kept" | string;
+  error?: string;
+}
+
+export interface RecoveryCleanupResult {
+  eligible: number;
+  moved: number;
+  busy: number;
+  kept: number;
+  dryRun: boolean;
+  items: RecoveryCleanupItem[];
+}
+
 export interface DeliveryWorktreeAvailability {
   available: boolean;
   reason?: string;

desktop/frontend/src/lib/useController.ts

@@ -18,6 +18,7 @@ import { getTranscriptStore } from "./transcriptStore";
 import { uiPerfTracker } from "./uiPerf";
 import { getLocale, t, type DictKey } from "./i18n";
 import { applyHydrateErrorState, hydratePlaceholderItems as resolveHydratePlaceholders } from "./hydrateErrorState";
+import { hasCachedLiveTurn, sameSessionPlaceholderItems, shouldApplyHydratedHistory } from "./hydrateHistoryApply";
 import { hydrateIdentityCurrent } from "./sessionIdentity";
 import { sameTodoList } from "./todoVisibility";
 import { fileDiffFromWire, summarize, summarizeFileDiff, type ToolFileDiff } from "./tools";
@@ -696,15 +697,6 @@ export function shouldReconcileStaleTurn(
   return Math.max(0, now - lastTurnActivityAt) >= timeoutMs;
 }
 
-function hasCachedLiveTurn(state: State | undefined): boolean {
-  if (!state?.running && !state?.turnActive) return false;
-  if (state.live || state.currentAssistant || state.pendingUser !== undefined) return true;
-  return state.items.some((item) =>
-    (item.kind === "assistant" && item.streaming) ||
-    (item.kind === "tool" && item.status === "running")
-  );
-}
-
 function hasReusableCachedTranscript(state: State | undefined, sessionPath?: string, revision?: number, digest?: string): boolean {
   if (!state || state.items.length === 0) return false;
   const expectedSessionPath = (sessionPath ?? "").trim();
@@ -2944,8 +2936,8 @@ export function useController() {
         dispatchTo(tabId, { type: "local_notice", level: "warn", text: errText });
         addBreadcrumb("tab.hydrate", `history failed ${tabId} ms=${Date.now() - historyStartedAt}`); return;
       }
-      if (!skipHistory && projection !== undefined && !foregroundTurnActive()) {
-        if (deferResetUntilHistory && stillCurrent()) dispatchTo(tabId, { type: "reset" });
+      if (projection !== undefined && shouldApplyHydratedHistory(skipHistory, true, foregroundTurnActive(), statesRef.current.get(tabId))) {
+        if (deferResetUntilHistory && stillCurrent() && !foregroundTurnActive()) dispatchTo(tabId, { type: "reset" });
         dispatchTo(tabId, {
           type: "history_replace",
           items: projection.items,
@@ -4614,9 +4606,10 @@ export function useController() {
       await reassertVisibleTabAfterStaleNavigation("topic.activate", meta.id);
       return meta;
     }
-    // Save previous tab's items so the new tab can use them as a placeholder
-    // during loading, avoiding a blank/Welcome flash before history arrives.
-    const prevItems = activeTabIdRef.current ? statesRef.current.get(activeTabIdRef.current)?.items : undefined;
+    const prevItems = sameSessionPlaceholderItems(
+      meta.sessionPath,
+      activeTabIdRef.current ? statesRef.current.get(activeTabIdRef.current) : undefined,
+    );
     pending.placeholderItems = prevItems;
     for (const id of Array.from(statesRef.current.keys())) {
       if (id !== meta.id) {
@@ -4632,9 +4625,7 @@ export function useController() {
     noteActivationStarted(pending.requestId, meta.id);
     dispatchTo(meta.id, { type: "optimistic_meta", meta: metaFromTab(meta, statesRef.current.get(meta.id)?.meta) });
     dispatchRuntimeStatusForTab(meta.id, meta, snapshotAt);
-    // The hydrate is driven by the activation's terminal "ready" event; until
-    // then keep the loading surface up with the previous tab's items as the
-    // placeholder (same no-flash behavior the immediate hydrate had).
+    // Ready hydrates; only same-session items are a safe placeholder.
     dispatchTo(meta.id, { type: "hydrate_start", reason: "open-topic", placeholderItems: prevItems });
     if (pending.terminal && pendingTopicActivationRef.current === pending) {
       // The terminal event beat the ticket resolution; process it now.

desktop/frontend/src/locales/en.ts

@@ -1243,13 +1243,29 @@ export const en = {
   "history.historySessionActions": "History session actions",
   "history.trashActions": "Trash actions",
 
-  // session recovery
-  "recovery.branch": "Conflict copy",
-  "recovery.badge": "Copy",
-  "recovery.noticeSavedCopy": "The session changed on disk, so the unsaved local transcript was kept as a conflict copy.",
-  "recovery.noticeKeptCurrent": "Repeated save conflicts were detected, so the current conflict copy was saved in an isolated recovery branch.",
+  // session recovery (advanced History language — avoid exposing internal terms)
+  "recovery.branch": "Saved version",
+  "recovery.badge": "Version",
+  "recovery.noticeSavedCopy": "The session changed on disk, so the unsaved local transcript was kept as another saved version.",
+  "recovery.noticeKeptCurrent": "Repeated save conflicts were detected, so the current version was saved separately.",
   "recovery.noticeAdopted": "The session changed on disk, so Reasonix adopted the newer transcript.",
   "recovery.noticeAdoptedCovered": "The session changed on disk, so Reasonix adopted the newer transcript; the local changes were already covered.",
+  "recovery.inspectLineage": "Other saved versions",
+  "recovery.lineageTitle": "Other saved versions",
+  "recovery.lineageSummary": "{branches} saved versions · {unresolved} with unique content",
+  "recovery.lineageEmpty": "No other saved versions.",
+  "recovery.previewCleanup": "Review safe cleanup",
+  "recovery.applyCleanup": "Move covered versions to Trash",
+  "recovery.cleanupConfirm": "{count} covered versions can be moved to Trash. Versions with unique content or that are in use will be kept.",
+  "recovery.cleanupResult": "Moved {moved}; busy {busy}; kept {kept}.",
+  "recovery.inUse": "in use",
+  "recovery.chooseBranch": "Set as default version",
+  "recovery.openVersion": "Open this version",
+  "recovery.role.covered_copy": "covered by a fuller version",
+  "recovery.role.adopted": "full version",
+  "recovery.role.preferred": "default version",
+  "recovery.role.diverged": "unique content",
+  "recovery.role.normal": "original",
 
   // project tree
   "projectTree.workspaceTitle": "Projects",
@@ -2588,7 +2604,7 @@ export const en = {
   "settings.addProvider.official.deepseek": "DeepSeek Official (Recommended)",
   "settings.addProvider.official.deepseekDesc": "Default Anthropic Messages API for Flash and Pro; server-side web search is enabled.",
   "settings.addProvider.preset.deepseekResponsesLabel": "DeepSeek Official Responses API",
-  "settings.addProvider.preset.deepseekResponsesDesc": "Stateless Responses API for Flash; server-side web search is enabled and may add cost.",
+  "settings.addProvider.preset.deepseekResponsesDesc": "Stateless Responses API for Flash and Pro; server-side web search is enabled and may add cost.",
   "settings.addProvider.preset.longcatOpenAIDesc": "LongCat Platform OpenAI-compatible endpoint with LongCat-2.0 default.",
   "settings.addProvider.preset.longcatAnthropicDesc": "LongCat Platform Anthropic-compatible Messages endpoint using Bearer auth.",
   "settings.addProvider.preset.tokenRhythmLabel": "Token Rhythm",

desktop/frontend/src/locales/zh-TW.ts

@@ -987,13 +987,29 @@ export const zhTW: Record<DictKey, string> = {
   "history.historySessionActions": "歷史會話操作",
   "history.trashActions": "回收站操作",
 
-  // 會話恢復
-  "recovery.branch": "衝突副本",
-  "recovery.badge": "副本",
-  "recovery.noticeSavedCopy": "偵測到會話在磁碟上發生變化，未儲存的本機記錄已保留為衝突副本。",
-  "recovery.noticeKeptCurrent": "偵測到重複儲存衝突，目前衝突副本已繼續儲存。",
+  // 會話恢復（歷史進階入口用詞，避免暴露內部術語）
+  "recovery.branch": "其他儲存版本",
+  "recovery.badge": "版本",
+  "recovery.noticeSavedCopy": "偵測到會話在磁碟上發生變化，未儲存的本機記錄已保留為其他儲存版本。",
+  "recovery.noticeKeptCurrent": "偵測到重複儲存衝突，目前版本已單獨儲存。",
   "recovery.noticeAdopted": "偵測到會話在磁碟上發生變化，已採用較新的記錄。",
   "recovery.noticeAdoptedCovered": "偵測到會話在磁碟上發生變化，已採用較新的記錄；本機改動已包含其中。",
+  "recovery.inspectLineage": "其他儲存版本",
+  "recovery.lineageTitle": "其他儲存版本",
+  "recovery.lineageSummary": "{branches} 個儲存版本 · {unresolved} 個含獨有內容",
+  "recovery.lineageEmpty": "沒有其他儲存版本。",
+  "recovery.previewCleanup": "檢查可安全清理項",
+  "recovery.applyCleanup": "將已覆蓋版本移到垃圾桶",
+  "recovery.cleanupConfirm": "{count} 個已被完整版本覆蓋的副本可以移到垃圾桶；含獨有內容或正在使用的版本會保留。",
+  "recovery.cleanupResult": "已移動 {moved} 個；佔用 {busy} 個；保留 {kept} 個。",
+  "recovery.inUse": "正在使用",
+  "recovery.chooseBranch": "設為預設版本",
+  "recovery.openVersion": "開啟此版本",
+  "recovery.role.covered_copy": "已被更完整版本覆蓋",
+  "recovery.role.adopted": "完整版本",
+  "recovery.role.preferred": "預設版本",
+  "recovery.role.diverged": "含獨有內容",
+  "recovery.role.normal": "原始會話",
 
   // 專案樹
   "projectTree.workspaceTitle": "專案",
@@ -1749,7 +1765,7 @@ export const zhTW: Record<DictKey, string> = {
   "settings.addProvider.official.deepseek": "DeepSeek 官方（推薦）",
   "settings.addProvider.official.deepseekDesc": "Anthropic Messages API，支援 Flash / Pro，預設開啟網頁搜尋。",
   "settings.addProvider.preset.deepseekResponsesLabel": "DeepSeek 官方 Responses API",
-  "settings.addProvider.preset.deepseekResponsesDesc": "無狀態 Responses API，僅支援 Flash，預設開啟網頁搜尋。",
+  "settings.addProvider.preset.deepseekResponsesDesc": "無狀態 Responses API，支援 Flash / Pro，預設開啟網頁搜尋。",
   "settings.addProvider.preset.longcatOpenAIDesc": "LongCat 開放平台 OpenAI-compatible 端點，預設 LongCat-2.0。",
   "settings.addProvider.preset.longcatAnthropicDesc": "LongCat 開放平台 Anthropic-compatible Messages 端點，使用 Bearer 認證。",
   "settings.addProvider.preset.tokenRhythmLabel": "基元律动",

desktop/frontend/src/locales/zh.ts

@@ -1245,12 +1245,28 @@ export const zh: Record<DictKey, string> = {
   "history.trashActions": "回收站操作",
 
   // 会话恢复
-  "recovery.branch": "冲突副本",
-  "recovery.badge": "副本",
-  "recovery.noticeSavedCopy": "检测到会话在磁盘上发生变化，未保存的本地记录已保留为冲突副本。",
-  "recovery.noticeKeptCurrent": "检测到重复保存冲突，当前冲突副本已继续保存。",
+  "recovery.branch": "其他保存版本",
+  "recovery.badge": "版本",
+  "recovery.noticeSavedCopy": "检测到会话在磁盘上发生变化，未保存的本地记录已保留为其他保存版本。",
+  "recovery.noticeKeptCurrent": "检测到重复保存冲突，当前版本已单独保存。",
   "recovery.noticeAdopted": "检测到会话在磁盘上发生变化，已采用较新的记录。",
   "recovery.noticeAdoptedCovered": "检测到会话在磁盘上发生变化，已采用较新的记录；本地改动已包含其中。",
+  "recovery.inspectLineage": "其他保存版本",
+  "recovery.lineageTitle": "其他保存版本",
+  "recovery.lineageSummary": "{branches} 个保存版本 · {unresolved} 个含独有内容",
+  "recovery.lineageEmpty": "没有其他保存版本。",
+  "recovery.previewCleanup": "检查可安全清理项",
+  "recovery.applyCleanup": "将已覆盖版本移到回收站",
+  "recovery.cleanupConfirm": "{count} 个已被完整版本覆盖的副本可以移到回收站；含独有内容或正在使用的版本会保留。",
+  "recovery.cleanupResult": "已移动 {moved} 个；占用 {busy} 个；保留 {kept} 个。",
+  "recovery.inUse": "正在使用",
+  "recovery.chooseBranch": "设为默认版本",
+  "recovery.openVersion": "打开此版本",
+  "recovery.role.covered_copy": "已被更完整版本覆盖",
+  "recovery.role.adopted": "完整版本",
+  "recovery.role.preferred": "默认版本",
+  "recovery.role.diverged": "含独有内容",
+  "recovery.role.normal": "原始会话",
 
   // 项目树
   "projectTree.workspaceTitle": "项目",
@@ -2591,7 +2607,7 @@ export const zh: Record<DictKey, string> = {
   "settings.addProvider.official.deepseek": "DeepSeek 官方（推荐）",
   "settings.addProvider.official.deepseekDesc": "Anthropic Messages API，支持 Flash / Pro，默认开启网页搜索。",
   "settings.addProvider.preset.deepseekResponsesLabel": "DeepSeek 官方 Responses API",
-  "settings.addProvider.preset.deepseekResponsesDesc": "无状态 Responses API，仅支持 Flash，默认开启网页搜索。",
+  "settings.addProvider.preset.deepseekResponsesDesc": "无状态 Responses API，支持 Flash / Pro，默认开启网页搜索。",
   "settings.addProvider.preset.longcatOpenAIDesc": "LongCat 开放平台 OpenAI-compatible 端点，默认 LongCat-2.0。",
   "settings.addProvider.preset.longcatAnthropicDesc": "LongCat 开放平台 Anthropic-compatible Messages 端点，使用 Bearer 认证。",
   "settings.addProvider.preset.tokenRhythmLabel": "基元律动",

desktop/frontend/src/styles.css

@@ -3372,13 +3372,18 @@ a[href] {
   }
 }
 .transcript {
+  /* Virtuoso sizes rows from the scroller clientWidth (padding included) but
+     lays them out in the content box. Horizontal padding here therefore makes
+     right-aligned bubbles extend under the workspace dock. Keep only vertical
+     inset on the scroller; rows own --transcript-inline-pad. */
+  --transcript-inline-pad: 32px;
   position: relative;
   height: 100%;
   overflow-y: auto;
   overflow-y: overlay;
   overflow-x: hidden;
   scrollbar-gutter: stable both-edges;
-  padding: 24px 32px 32px;
+  padding: 24px 0 32px;
   scrollbar-width: thin;
   scrollbar-color: var(--scrollbar-thumb) var(--scrollbar-track);
 }
@@ -3415,11 +3420,17 @@ a[href] {
 .transcript__row {
   position: relative;
   display: flow-root;
+  box-sizing: border-box;
   width: 100%;
+  padding-left: var(--transcript-inline-pad, 32px);
+  padding-right: var(--transcript-inline-pad, 32px);
 }
 .transcript__header {
   display: flow-root;
+  box-sizing: border-box;
   width: 100%;
+  padding-left: var(--transcript-inline-pad, 32px);
+  padding-right: var(--transcript-inline-pad, 32px);
 }
 .transcript__header > * {
   max-width: var(--maxw);
@@ -3458,7 +3469,8 @@ a[href] {
 .transcript__row .tool,
 .transcript__row .process-card,
 .transcript__row .readonly-batch,
-.transcript__row .tool-group {
+.transcript__row .tool-group,
+.transcript__row .md > * {
   content-visibility: visible;
   contain-intrinsic-size: none;
 }
@@ -14877,6 +14889,62 @@ body > .mermaid-diagram--fullscreen {
   gap: 8px;
   flex-shrink: 0;
 }
+
+.recovery-lineage-dialog {
+  width: min(680px, calc(100vw - 48px));
+  height: auto;
+  max-height: min(720px, calc(100vh - 64px));
+}
+.recovery-lineage-dialog .management-modal__title {
+  display: flex;
+  align-items: center;
+  gap: 7px;
+}
+.recovery-lineage-dialog__body {
+  min-height: 120px;
+  overflow: auto;
+  padding: 12px 18px;
+}
+.recovery-lineage-dialog__member {
+  padding: 10px 2px;
+  border-bottom: 1px solid var(--border);
+}
+.recovery-lineage-dialog__member-name {
+  color: var(--fg);
+  font-size: var(--text-sm);
+  font-family: var(--font-mono);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.recovery-lineage-dialog__member-meta {
+  display: flex;
+  gap: 10px;
+  margin-top: 4px;
+  color: var(--fg-faint);
+  font-size: var(--text-xs);
+}
+.recovery-lineage-dialog__choose {
+  border: 0;
+  padding: 0;
+  background: transparent;
+  color: var(--accent);
+  cursor: pointer;
+  font: inherit;
+}
+.recovery-lineage-dialog__choose:disabled { opacity: 0.5; cursor: default; }
+.recovery-lineage-dialog__notice {
+  margin-top: 12px;
+  padding: 10px 12px;
+  border-radius: 8px;
+  background: var(--bg-elev);
+  color: var(--fg-muted);
+  font-size: var(--text-sm);
+}
+.recovery-lineage-dialog__actions {
+  padding: 12px 18px;
+  border-top: 1px solid var(--border);
+}
 @keyframes modal-in {
   0% {
     transform: translate3d(0, 10px, 0) scale(0.982);
@@ -15073,7 +15141,8 @@ body > .mermaid-diagram--fullscreen {
   font-size: var(--font-control);
 }
 .history-preview__body .transcript {
-  padding: 14px 14px 18px;
+  --transcript-inline-pad: 14px;
+  padding: 14px 0 18px;
 }
 .history-preview__body .transcript > * {
   max-width: none;
@@ -21306,7 +21375,8 @@ body > .mermaid-diagram--fullscreen {
     display: flex;
   }
   .transcript {
-    padding: 18px 16px 28px;
+    --transcript-inline-pad: 16px;
+    padding: 18px 0 28px;
   }
   .jump-bar {
     display: none;
@@ -26663,7 +26733,7 @@ body > .mermaid-diagram--fullscreen {
 }
 
 .transcript {
-  padding: 24px 32px 28px;
+  padding: 24px 0 28px;
 }
 
 .transcript > * {
@@ -27942,7 +28012,7 @@ body > .mermaid-diagram--fullscreen {
 }
 
 :root[data-theme-style] .transcript {
-  padding: 24px 32px 28px;
+  padding: 24px 0 28px;
 }
 
 :root[data-theme-style] .transcript--empty {
@@ -28549,7 +28619,8 @@ body > .mermaid-diagram--fullscreen {
 }
 
 :root[data-theme-style] .history-preview__body .transcript {
-  padding: 14px;
+  --transcript-inline-pad: 14px;
+  padding: 14px 0;
 }
 
 :root[data-theme-style] .settings-center__nav {

desktop/recovery_gc.go

@@ -2,67 +2,21 @@ package main
 
 import (
 	"log/slog"
+	"os"
 	"time"
 
 	"reasonix/internal/agent"
-	"reasonix/internal/config"
+	"reasonix/internal/sessioncatalog"
 )
 
-// recoveryGCInterval bounds how often the background sweep repeats after the
-// startup run. Covered copies are also reclaimed by the shorter startup grace.
-const recoveryGCInterval = 6 * time.Hour
-
-// recoveryGCFollowUpDelay re-runs the short-grace sweep once after startup so
-// branches that just crossed the 15-minute idle line are not left until the
-// next 6-hour tick.
-const recoveryGCFollowUpDelay = 20 * time.Minute
-
-// startRecoveryGC waits for tab restore, runs a short-grace startup sweep (and
-// one follow-up), then repeats on the long interval until cancelled. The wait
-// is load-bearing: a pre-restore sweep sees every saved tab as closed, letting
-// DeleteSession overwrite desktop-tabs.json with an empty snapshot.
-func (a *App) startRecoveryGC() {
-	a.goSafe("recoveryGC", func() {
-		select {
-		case <-a.tabsRestoredSignal():
-		case <-a.ctx.Done():
-			return
-		}
-		startup := time.NewTimer(agent.RecoveryGCStartupGracePeriod)
-		if !waitRecoveryGCStartup(a.ctx.Done(), startup.C) {
-			if !startup.Stop() {
-				select {
-				case <-startup.C:
-				default:
-				}
-			}
-			return
-		}
-		// Protect every upgraded user for a full startup grace before reclaiming.
-		a.sweepReclaimableRecoveryBranchesWithGrace(agent.RecoveryGCStartupGracePeriod)
-		followUp := time.NewTimer(recoveryGCFollowUpDelay)
-		ticker := time.NewTicker(recoveryGCInterval)
-		defer ticker.Stop()
-		for {
-			select {
-			case <-a.ctx.Done():
-				if !followUp.Stop() {
-					select {
-					case <-followUp.C:
-					default:
-					}
-				}
-				return
-			case <-followUp.C:
-				// Second short-grace pass, then fall through to long-interval only.
-				a.sweepReclaimableRecoveryBranchesWithGrace(agent.RecoveryGCStartupGracePeriod)
-				followUp.C = nil
-			case <-ticker.C:
-				a.sweepReclaimableRecoveryBranches()
-			}
-		}
-	})
-}
+// startRecoveryGC is intentionally a no-op for physical moves.
+//
+// Catalog v4 folds recovery lineages into one ordinary list row. Automatic
+// startup/upgrade/timer GC must not move JSONL/meta into trash — only explicit
+// CleanRecoveryLineage (UI, with preview) and `reasonix sessions cleanup
+// --apply` may reclaim covered copies. reclaimRecoveryBranchesIn remains for
+// those explicit entry points and focused tests.
+func (a *App) startRecoveryGC() {}
 
 func waitRecoveryGCStartup(done <-chan struct{}, elapsed <-chan time.Time) bool {
 	select {
@@ -73,31 +27,35 @@ func waitRecoveryGCStartup(done <-chan struct{}, elapsed <-chan time.Time) bool
 	}
 }
 
-// sweepReclaimableRecoveryBranches trashes conflict-recovery branches that
-// preserve nothing unique (their content is covered by a still-present parent
-// session), were never continued on, sat idle past the grace period, and are
-// not held by any runtime. Trashing — never hard deletion — keeps every swept
-// branch recoverable from the session trash. Returns how many were reclaimed.
-func (a *App) sweepReclaimableRecoveryBranches() int {
-	return a.sweepReclaimableRecoveryBranchesWithGrace(agent.RecoveryGCGracePeriod)
-}
-
-func (a *App) sweepReclaimableRecoveryBranchesWithGrace(grace time.Duration) int {
-	return a.reclaimRecoveryBranchesIn(recoveryGCDirs(), time.Now(), grace)
-}
-
 func (a *App) reclaimRecoveryBranchesIn(dirs []string, now time.Time, grace time.Duration) int {
 	if grace <= 0 {
 		grace = agent.RecoveryGCGracePeriod
 	}
 	reclaimed := 0
 	for _, dir := range dirs {
+		removed := map[string]bool{}
+		if catalog := a.sessionCatalog.Load(); catalog != nil {
+			groups, err := catalog.ListRecoveryGroups(a.bootContext(), dir)
+			if err != nil {
+				slog.Warn("desktop: list recovery lineages for GC", "dir", dir, "err", err)
+			} else {
+				for _, group := range groups {
+					for _, path := range a.reclaimAdoptedRecoveryGroup(group, now, grace) {
+						removed[sessionRuntimeKey(path)] = true
+						reclaimed++
+					}
+				}
+			}
+		}
 		reclaimable, err := agent.ReclaimableRecoveryBranches(dir, now, grace)
 		if err != nil {
 			slog.Warn("desktop: scan reclaimable recovery branches", "dir", dir, "err", err)
 			continue
 		}
 		for _, path := range reclaimable {
+			if removed[sessionRuntimeKey(path)] {
+				continue
+			}
 			// Re-check liveness right before disposal: the scan is a snapshot,
 			// and the user may have opened the branch since.
 			if agent.SessionLeaseHeld(path) || a.sessionOpenInAnyTab(path) {
@@ -120,29 +78,48 @@ func (a *App) reclaimRecoveryBranchesIn(dirs []string, now time.Time, grace time
 	return reclaimed
 }
 
-// recoveryGCDirs returns every session directory the desktop lists sessions
-// from: the global desktop and legacy shared dirs plus each saved project's
-// session dirs, deduplicated.
-func recoveryGCDirs() []string {
-	seen := map[string]bool{}
-	var dirs []string
-	add := func(dir string) {
-		key := projectRootKey(dir)
-		if dir == "" || seen[key] {
-			return
-		}
-		seen[key] = true
-		dirs = append(dirs, dir)
+// reclaimAdoptedRecoveryGroup compacts an entire legacy recovery chain once a
+// canonical leaf has proved it covers every member. Every candidate is still
+// revalidated under removal guards immediately before it is moved to trash.
+func (a *App) reclaimAdoptedRecoveryGroup(group sessioncatalog.RecoveryGroup, now time.Time, grace time.Duration) []string {
+	if group.State != "adopted" || group.CanonicalPath == "" || group.ID == "" {
+		return nil
 	}
-	add(desktopSessionDir(globalWorkspaceRoot()))
-	add(config.SessionDir())
-	for _, project := range loadProjectsFile().Projects {
-		if root := normalizeProjectRoot(project.Root); root != "" {
-			add(desktopSessionDir(root))
-			add(config.ProjectSessionDir(root))
+	candidates := []string{}
+	for _, member := range group.Members {
+		if member.Path == group.CanonicalPath || member.RecoveryRole != sessioncatalog.RecoveryRoleCoveredCopy {
+			continue
 		}
+		info, err := os.Stat(member.Path)
+		if err != nil || now.Sub(info.ModTime()) < grace {
+			continue
+		}
+		candidates = append(candidates, member.Path)
 	}
-	return dirs
+	if len(candidates) == 0 {
+		return nil
+	}
+	defer a.lockRuntimeMutation("gc-recovery-lineage")()
+	a.sessionRemovalMu.Lock()
+	defer a.sessionRemovalMu.Unlock()
+	if a.sessionOpenInAnyTab(group.CanonicalPath) || agent.SessionLeaseHeld(group.CanonicalPath) {
+		return nil
+	}
+	if err := agent.ReparentRecoveryCanonical(group.CanonicalPath, group.ID, group.Directory); err != nil {
+		return nil
+	}
+	moved := []string{}
+	for _, path := range candidates {
+		if a.sessionOpenInAnyTab(path) || agent.SessionLeaseHeld(path) {
+			continue
+		}
+		if err := agent.TrashRecoveryBranchCoveredBy(path, group.CanonicalPath, group.Directory); err != nil {
+			continue
+		}
+		moved = append(moved, path)
+		a.removeSessionCatalogPath(path, "recovery_lineage_gc")
+	}
+	return moved
 }
 
 // sessionOpenInAnyTab reports whether any tab's current session is path.

desktop/recovery_lineage.go

@@ -0,0 +1,262 @@
+package main
+
+import (
+	"errors"
+	"path/filepath"
+
+	"reasonix/internal/agent"
+	"reasonix/internal/sessioncatalog"
+)
+
+type RecoveryLineageMember struct {
+	Path      string `json:"path"`
+	Role      string `json:"role"`
+	Canonical bool   `json:"canonical"`
+	Turns     int    `json:"turns"`
+	Open      bool   `json:"open"`
+	Running   bool   `json:"running"`
+}
+
+type RecoveryLineageView struct {
+	GroupID         string                  `json:"groupId"`
+	State           string                  `json:"state"`
+	BranchCount     int                     `json:"branchCount"`
+	Unresolved      int                     `json:"unresolved"`
+	CleanupEligible int                     `json:"cleanupEligible"`
+	Members         []RecoveryLineageMember `json:"members"`
+}
+
+type RecoveryCleanupRequest struct {
+	Scope         string `json:"scope"`
+	WorkspaceRoot string `json:"workspaceRoot,omitempty"`
+	TopicID       string `json:"topicId"`
+	Apply         bool   `json:"apply"`
+}
+
+type RecoveryPreferenceRequest struct {
+	Scope         string `json:"scope"`
+	WorkspaceRoot string `json:"workspaceRoot,omitempty"`
+	TopicID       string `json:"topicId"`
+	Path          string `json:"path"`
+}
+
+type RecoveryCleanupItem struct {
+	Path   string `json:"path"`
+	Status string `json:"status"`
+	Error  string `json:"error,omitempty"`
+}
+
+type RecoveryCleanupResult struct {
+	Eligible int                   `json:"eligible"`
+	Moved    int                   `json:"moved"`
+	Busy     int                   `json:"busy"`
+	Kept     int                   `json:"kept"`
+	DryRun   bool                  `json:"dryRun"`
+	Items    []RecoveryCleanupItem `json:"items"`
+}
+
+func (a *App) GetRecoveryLineage(key ProjectTopicKey) RecoveryLineageView {
+	out := RecoveryLineageView{Members: []RecoveryLineageMember{}}
+	catalog := a.sessionCatalog.Load()
+	if catalog == nil {
+		return out
+	}
+	topic, ok, err := catalog.GetTopic(a.bootContext(), sessioncatalog.TopicKey{Scope: key.Scope, WorkspaceRoot: key.WorkspaceRoot, TopicID: key.TopicID})
+	if err != nil || !ok {
+		return out
+	}
+	groupID, directory := "", ""
+	for _, record := range topic.Sessions {
+		if record.Recovered && record.RecoveryGroupID != "" {
+			groupID, directory = record.RecoveryGroupID, filepath.Dir(record.Path)
+			break
+		}
+	}
+	if groupID == "" || directory == "" {
+		return out
+	}
+	groups, err := catalog.ListRecoveryGroups(a.bootContext(), directory)
+	if err != nil {
+		return out
+	}
+	members := []sessioncatalog.SessionRecord{}
+	for _, group := range groups {
+		if group.ID == groupID {
+			members = group.Members
+			out.State = group.State
+			break
+		}
+	}
+	out.GroupID = groupID
+	_, overlays := a.catalogRuntimeOverlays()
+	for _, record := range members {
+		overlay := overlays[sessionRuntimeKey(record.Path)]
+		out.Members = append(out.Members, RecoveryLineageMember{Path: record.Path, Role: record.RecoveryRole,
+			Canonical: record.RecoveryCanonical, Turns: record.Turns, Open: overlay.open, Running: overlay.running})
+		out.BranchCount++
+		if record.RecoveryRole == sessioncatalog.RecoveryRoleDiverged {
+			out.Unresolved++
+		}
+		if record.RecoveryRole == sessioncatalog.RecoveryRoleCoveredCopy {
+			out.CleanupEligible++
+		}
+	}
+	if out.State == "" {
+		out.State = topic.RecoveryState
+	}
+	if out.State == "preferred" {
+		out.Unresolved = 0
+	}
+	return out
+}
+
+// ChooseRecoveryBranch changes only the default open target. Diverged content
+// remains on disk and is never made cleanup-eligible by this choice.
+func (a *App) ChooseRecoveryBranch(req RecoveryPreferenceRequest) error {
+	catalog := a.sessionCatalog.Load()
+	if catalog == nil {
+		return errors.New("session catalog is unavailable")
+	}
+	topic, ok, err := catalog.GetTopic(a.bootContext(), sessioncatalog.TopicKey{Scope: req.Scope, WorkspaceRoot: req.WorkspaceRoot, TopicID: req.TopicID})
+	if err != nil || !ok {
+		return errors.New("recovery lineage is unavailable")
+	}
+	groupID, dir := "", ""
+	for _, record := range topic.Sessions {
+		if record.Recovered && record.RecoveryGroupID != "" {
+			groupID, dir = record.RecoveryGroupID, filepath.Dir(record.Path)
+			break
+		}
+	}
+	groups, err := catalog.ListRecoveryGroups(a.bootContext(), dir)
+	if err != nil {
+		return errors.New("recovery lineage is unavailable")
+	}
+	paths := []string{}
+	chosen := ""
+	for _, group := range groups {
+		if group.ID != groupID {
+			continue
+		}
+		for _, member := range group.Members {
+			paths = append(paths, member.Path)
+			if sessionRuntimeKey(member.Path) == sessionRuntimeKey(req.Path) && member.RecoveryRole != sessioncatalog.RecoveryRoleCoveredCopy {
+				chosen = member.Path
+			}
+		}
+	}
+	if chosen == "" {
+		return errors.New("selected branch is outside the recovery lineage")
+	}
+	defer a.lockRuntimeMutation("choose-recovery-branch")()
+	a.sessionRemovalMu.Lock()
+	defer a.sessionRemovalMu.Unlock()
+	if err := agent.SetRecoveryPreferred(paths, chosen); err != nil {
+		return errors.New("could not save the recovery branch choice")
+	}
+	if err := catalog.ReconcileDirectory(a.bootContext(), sessioncatalog.DirectoryTarget{Path: dir, Scope: req.Scope, WorkspaceRoot: req.WorkspaceRoot}); err != nil {
+		return errors.New("the branch choice was saved but the session catalog could not refresh")
+	}
+	a.emitProjectTreeChangedForSessionDirs(dir)
+	return nil
+}
+
+// CleanRecoveryLineage performs one backend-owned, revalidated cleanup batch.
+// It never purges and never moves diverged content.
+func (a *App) CleanRecoveryLineage(req RecoveryCleanupRequest) RecoveryCleanupResult {
+	result := RecoveryCleanupResult{DryRun: !req.Apply, Items: []RecoveryCleanupItem{}}
+	catalog := a.sessionCatalog.Load()
+	if catalog == nil {
+		return result
+	}
+	topic, ok, err := catalog.GetTopic(a.bootContext(), sessioncatalog.TopicKey{Scope: req.Scope, WorkspaceRoot: req.WorkspaceRoot, TopicID: req.TopicID})
+	if err != nil || !ok {
+		return result
+	}
+	canonical := ""
+	rootID := ""
+	for _, record := range topic.Sessions {
+		if record.RecoveryCanonical && (record.RecoveryRole == sessioncatalog.RecoveryRoleAdopted || record.RecoveryRole == sessioncatalog.RecoveryRolePreferred) {
+			canonical = record.Path
+			rootID = record.RecoveryGroupID
+			break
+		}
+	}
+	if canonical == "" || rootID == "" {
+		return result
+	}
+	dir := filepath.Dir(canonical)
+	groups, err := catalog.ListRecoveryGroups(a.bootContext(), dir)
+	if err != nil {
+		return result
+	}
+	members := []sessioncatalog.SessionRecord{}
+	for _, group := range groups {
+		if group.ID == rootID {
+			members = group.Members
+			break
+		}
+	}
+	candidates := []sessioncatalog.SessionRecord{}
+	for _, record := range members {
+		if record.Path == canonical || record.RecoveryRole != sessioncatalog.RecoveryRoleCoveredCopy {
+			continue
+		}
+		result.Eligible++
+		candidates = append(candidates, record)
+		result.Items = append(result.Items, RecoveryCleanupItem{Path: record.Path, Status: "eligible"})
+	}
+	if !req.Apply || len(candidates) == 0 {
+		return result
+	}
+	defer a.lockRuntimeMutation("clean-recovery-lineage")()
+	a.sessionRemovalMu.Lock()
+	defer a.sessionRemovalMu.Unlock()
+	if a.sessionOpenInAnyTab(canonical) || agent.SessionLeaseHeld(canonical) {
+		for index := range result.Items {
+			result.Items[index].Status = "busy"
+			result.Busy++
+		}
+		return result
+	}
+	if err := agent.ReparentRecoveryCanonical(canonical, rootID, dir); err != nil {
+		for index := range result.Items {
+			if errors.Is(err, agent.ErrSessionLeaseHeld) {
+				result.Items[index].Status = "busy"
+				result.Busy++
+			} else {
+				result.Items[index].Status = "kept"
+				result.Items[index].Error = "recovery branch changed and was kept"
+				result.Kept++
+			}
+		}
+		return result
+	}
+	for index, record := range candidates {
+		item := &result.Items[index]
+		if a.sessionOpenInAnyTab(record.Path) || agent.SessionLeaseHeld(record.Path) {
+			item.Status = "busy"
+			result.Busy++
+			continue
+		}
+		if err := agent.TrashRecoveryBranchCoveredBy(record.Path, canonical, dir); err != nil {
+			item.Status = "kept"
+			if errors.Is(err, agent.ErrSessionLeaseHeld) {
+				item.Status = "busy"
+				result.Busy++
+			} else {
+				item.Error = "recovery branch changed and was kept"
+				result.Kept++
+			}
+		} else {
+			item.Status = "moved"
+			result.Moved++
+			a.removeSessionCatalogPath(record.Path, "recovery_lineage_cleaned")
+		}
+	}
+	if result.Moved > 0 {
+		a.emitProjectTreeChangedForSessionDirs(dir)
+		a.invalidatePromptHistoryCache()
+	}
+	return result
+}

desktop/session_canonical_retarget.go

@@ -26,24 +26,14 @@ func (a *App) resolveCanonicalSessionPath(path string) string {
 	}
 	if rec.TopicID == "" {
 		// Group by recovery group when topic is unset.
-		if rec.RecoveryCanonical && rec.RecoveryRole == sessioncatalog.RecoveryRoleAdopted {
+		if rec.RecoveryCanonical && (rec.RecoveryRole == sessioncatalog.RecoveryRoleAdopted || rec.RecoveryRole == sessioncatalog.RecoveryRolePreferred) {
 			return ""
 		}
 		return ""
 	}
-	page, err := catalog.ListSessions(ctx, sessioncatalog.SessionPageRequest{
-		Scope:         rec.Scope,
-		WorkspaceRoot: rec.WorkspaceRoot,
-		Limit:         sessioncatalog.MaxLimit,
-	})
-	if err != nil {
+	topic, ok, err := catalog.GetTopic(ctx, sessioncatalog.TopicKey{Scope: rec.Scope, WorkspaceRoot: rec.WorkspaceRoot, TopicID: rec.TopicID})
+	if err != nil || !ok {
 		return ""
 	}
-	var sameTopic []sessioncatalog.SessionRecord
-	for _, s := range page.Items {
-		if s.TopicID == rec.TopicID && s.Scope == rec.Scope && s.WorkspaceRoot == rec.WorkspaceRoot {
-			sameTopic = append(sameTopic, s)
-		}
-	}
-	return sessioncatalog.CanonicalSessionPathForTopic(sameTopic, path)
+	return sessioncatalog.CanonicalSessionPathForTopic(topic.Sessions, path)
 }

desktop/session_catalog.go

@@ -16,6 +16,8 @@ import (
 	"reasonix/internal/taskcatalog"
 )
 
+const sessionCatalogMetadataSyncTimeout = 30 * time.Second
+
 type SessionCatalogStatus struct {
 	State           string `json:"state"`
 	Mode            string `json:"mode"`
@@ -155,7 +157,7 @@ func (a *App) startSessionCatalog(rebuild bool) {
 			return
 		}
 		a.sessionCatalog.Store(catalog)
-		if err := a.syncSessionCatalogMetadata(ctx, catalog); err != nil && !errors.Is(err, context.Canceled) {
+		if err := a.syncSessionCatalogMetadataBounded(ctx, catalog); err != nil && !errors.Is(err, context.Canceled) {
 			slog.Warn("desktop: sync session catalog metadata", "err", err)
 		}
 		select {
@@ -171,7 +173,7 @@ func (a *App) startSessionCatalog(rebuild bool) {
 			// Legacy assignment is deliberately background-only. It can scan and
 			// repair old metadata, but no project-tree or controller request waits.
 			if migrated := migrateLegacySessionsIntoGlobalTopics(target.Path); len(migrated) > 0 {
-				_ = a.syncSessionCatalogMetadata(ctx, catalog)
+				_ = a.syncSessionCatalogMetadataBounded(ctx, catalog)
 			}
 			if err := catalog.ReconcileDirectory(ctx, target); err != nil && !errors.Is(err, context.Canceled) {
 				slog.Debug("desktop: reconcile session catalog directory", "dir", target.Path, "err", err)
@@ -182,12 +184,12 @@ func (a *App) startSessionCatalog(rebuild bool) {
 		for {
 			select {
 			case <-ticker.C:
-				if err := a.syncSessionCatalogMetadata(ctx, catalog); err != nil && !errors.Is(err, context.Canceled) {
+				if err := a.syncSessionCatalogMetadataBounded(ctx, catalog); err != nil && !errors.Is(err, context.Canceled) {
 					slog.Debug("desktop: refresh session catalog metadata", "err", err)
 				}
 				for _, target := range a.sessionCatalogTargets() {
 					if migrated := migrateLegacySessionsIntoGlobalTopics(target.Path); len(migrated) > 0 {
-						_ = a.syncSessionCatalogMetadata(ctx, catalog)
+						_ = a.syncSessionCatalogMetadataBounded(ctx, catalog)
 					}
 					catalog.RequestReconcile(target)
 				}
@@ -322,6 +324,17 @@ func (a *App) indexRestoredSessionPaths(ctx context.Context, catalog *sessioncat
 	}
 }
 
+// syncSessionCatalogMetadataBounded is the only form the long-lived catalog
+// goroutine may use. SyncMetadata runs under the catalog's single-writer mutex,
+// so one transaction that never returns silently wedges every later index,
+// reconcile, and revision bump — and the sidebar then stops updating for the
+// rest of the process lifetime instead of failing loudly.
+func (a *App) syncSessionCatalogMetadataBounded(ctx context.Context, catalog *sessioncatalog.Catalog) error {
+	ctx, cancel := context.WithTimeout(ctx, sessionCatalogMetadataSyncTimeout)
+	defer cancel()
+	return a.syncSessionCatalogMetadata(ctx, catalog)
+}
+
 func (a *App) syncSessionCatalogMetadata(ctx context.Context, catalog *sessioncatalog.Catalog) error {
 	f := loadProjectsFile()
 	deleted := map[string]bool{}

desktop/session_catalog_app_test.go

@@ -4,9 +4,12 @@ import (
 	"context"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 	"time"
 
+	"reasonix/internal/agent"
+	"reasonix/internal/provider"
 	"reasonix/internal/sessioncatalog"
 )
 
@@ -116,3 +119,209 @@ func TestProjectTreeShellSurvivesCatalogRevisionRace(t *testing.T) {
 		t.Fatalf("snapshot projects = %#v, want Shell Race", snapshot.Projects)
 	}
 }
+
+func TestUpgradeLegacyRecoveryChainNeedsNoUserActionForOneRowSidebar(t *testing.T) {
+	isolateDesktopUserDirs(t)
+	dir := desktopSessionDir(globalWorkspaceRoot())
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	save := func(path, topic string, messages ...provider.Message) {
+		t.Helper()
+		session := agent.NewSession("sys")
+		for _, message := range messages {
+			session.Add(message)
+		}
+		if err := session.Save(path); err != nil {
+			t.Fatal(err)
+		}
+		if err := agent.SaveBranchMetaPreserveUpdated(path, agent.BranchMeta{
+			ID: agent.BranchID(path), Scope: "global", TopicID: topic,
+			TopicTitle: "Upgraded conversation",
+		}); err != nil {
+			t.Fatal(err)
+		}
+	}
+	q := provider.Message{Role: provider.RoleUser, Content: "question"}
+	a := provider.Message{Role: provider.RoleAssistant, Content: "answer"}
+	next := provider.Message{Role: provider.RoleUser, Content: "continue"}
+	done := provider.Message{Role: provider.RoleAssistant, Content: "done"}
+	root := filepath.Join(dir, "root.jsonl")
+	copy := filepath.Join(dir, "copy.jsonl")
+	leaf := filepath.Join(dir, "leaf.jsonl")
+	save(root, "conversation", q, a)
+	save(copy, "legacy-copy-topic", q, a)
+	save(leaf, "legacy-leaf-topic", q, a, next, done)
+	for path, meta := range map[string]agent.BranchMeta{
+		copy: {ID: "copy", Scope: "global", TopicID: "legacy-copy-topic", Recovered: true, ParentID: "root", RecoveryDepth: 1},
+		leaf: {ID: "leaf", Scope: "global", TopicID: "legacy-leaf-topic", Recovered: true, ParentID: "copy", RecoveryDepth: 2},
+	} {
+		if err := agent.SaveBranchMetaPreserveUpdated(path, meta); err != nil {
+			t.Fatal(err)
+		}
+	}
+	app := NewApp()
+	installSessionCatalogForTest(t, app, dir, "global", "")
+	page, err := app.ListProjectTopics(ProjectTopicPageRequest{Scope: "global", Limit: 50})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(page.Items) != 1 || page.Items[0].TopicID != "conversation" || len(page.Items[0].Children) != 0 {
+		t.Fatalf("zero-touch upgraded sidebar = %+v, want one ordinary conversation row", page.Items)
+	}
+	if page.Items[0].RecoveryBranchCount != 0 || page.Items[0].RecoveryUnresolvedCount != 0 ||
+		page.Items[0].Status == topicStatusDivergedRecovery {
+		// Recovery counts and conflict status belong only to History advanced
+		// views; the ordinary root row must stay a plain conversation line.
+		t.Fatalf("ordinary row leaked recovery decoration: %+v", page.Items[0])
+	}
+}
+
+func TestListProjectTopicsSurfacesLiveTabWhileCatalogLags(t *testing.T) {
+	isolateDesktopUserDirs(t)
+	root := t.TempDir()
+	if err := addProject(root, "Lagging Catalog"); err != nil {
+		t.Fatal(err)
+	}
+	sessionDir := desktopSessionDir(root)
+	if err := os.MkdirAll(sessionDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	app := NewApp()
+	installSessionCatalogForTest(t, app, sessionDir, "project", root)
+	app.tabs["tab-1"] = &WorkspaceTab{
+		ID: "tab-1", Scope: "project", WorkspaceRoot: root,
+		TopicID: "topic_20260812-082637_live", TopicTitle: "Ownership Hub",
+	}
+
+	page, err := app.ListProjectTopics(ProjectTopicPageRequest{Scope: "project", WorkspaceRoot: root})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(page.Items) != 1 || page.Items[0].TopicID != "topic_20260812-082637_live" {
+		t.Fatalf("page items = %#v, want the live tab's topic", page.Items)
+	}
+	if page.Items[0].CreatedAt <= 0 {
+		t.Fatalf("createdAt = %d, want the topic's creation time", page.Items[0].CreatedAt)
+	}
+}
+
+func TestListProjectTopicsDoesNotDuplicateIndexedLiveTab(t *testing.T) {
+	isolateDesktopUserDirs(t)
+	root := t.TempDir()
+	if err := addProject(root, "Indexed"); err != nil {
+		t.Fatal(err)
+	}
+	sessionDir := desktopSessionDir(root)
+	if err := os.MkdirAll(sessionDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	sessionPath := filepath.Join(sessionDir, "live.jsonl")
+	if err := os.WriteFile(sessionPath, []byte(`{"role":"user","content":"hi"}`+"\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := agent.UpdateBranchMeta(sessionPath, false, func(meta *agent.BranchMeta) error {
+		meta.TopicID = "topic-indexed"
+		meta.TopicTitle = "Indexed Topic"
+		meta.WorkspaceRoot = root
+		meta.Scope = "project"
+		return nil
+	}); err != nil {
+		t.Fatal(err)
+	}
+	app := NewApp()
+	installSessionCatalogForTest(t, app, sessionDir, "project", root)
+	app.tabs["tab-1"] = &WorkspaceTab{
+		ID: "tab-1", Scope: "project", WorkspaceRoot: root,
+		TopicID: "topic-indexed", TopicTitle: "Indexed Topic", SessionPath: sessionPath,
+	}
+
+	page, err := app.ListProjectTopics(ProjectTopicPageRequest{Scope: "project", WorkspaceRoot: root})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(page.Items) != 1 {
+		t.Fatalf("page items = %#v, want the catalog row only", page.Items)
+	}
+}
+
+func TestListProjectTopicsFoldsRestoredLegacyTopicTabIntoOneRow(t *testing.T) {
+	isolateDesktopUserDirs(t)
+	dir := desktopSessionDir(globalWorkspaceRoot())
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	save := func(path, topic string) {
+		t.Helper()
+		session := agent.NewSession("sys")
+		session.Add(provider.Message{Role: provider.RoleUser, Content: "question"})
+		session.Add(provider.Message{Role: provider.RoleAssistant, Content: "answer"})
+		if err := session.Save(path); err != nil {
+			t.Fatal(err)
+		}
+		if err := agent.SaveBranchMetaPreserveUpdated(path, agent.BranchMeta{
+			ID: agent.BranchID(path), Scope: "global", TopicID: topic,
+			TopicTitle: "Upgraded conversation",
+		}); err != nil {
+			t.Fatal(err)
+		}
+	}
+	root := filepath.Join(dir, "root.jsonl")
+	copyPath := filepath.Join(dir, "copy.jsonl")
+	save(root, "conversation")
+	save(copyPath, "legacy-copy-topic")
+	if err := agent.SaveBranchMetaPreserveUpdated(copyPath, agent.BranchMeta{
+		ID: "copy", Scope: "global", TopicID: "legacy-copy-topic",
+		Recovered: true, ParentID: "root", RecoveryDepth: 1,
+	}); err != nil {
+		t.Fatal(err)
+	}
+	app := NewApp()
+	installSessionCatalogForTest(t, app, dir, "global", "")
+	// A restored pre-upgrade tab still carries the legacy topic ID for the
+	// recovery copy that the catalog re-anchored onto the root logical topic.
+	// withLiveTopics must dedupe by the projected topic, not the tab's one,
+	// so the sidebar keeps exactly one row for the conversation.
+	app.tabs["tab-1"] = &WorkspaceTab{
+		ID: "tab-1", Scope: "global",
+		TopicID: "legacy-copy-topic", TopicTitle: "Upgraded conversation",
+		SessionPath: copyPath,
+	}
+	page, err := app.ListProjectTopics(ProjectTopicPageRequest{Scope: "global", Limit: 50})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(page.Items) != 1 || page.Items[0].TopicID != "conversation" {
+		t.Fatalf("page items = %#v, want one folded conversation row", page.Items)
+	}
+	if !page.Items[0].Open {
+		t.Fatal("open recovery tab must aggregate onto the logical row")
+	}
+}
+
+// The catalog goroutine outlives every request, so an unbounded metadata sync
+// there can hold the catalog's single-writer mutex forever and freeze the whole
+// sidebar. Guard the call shape, not just today's behaviour.
+func TestSessionCatalogGoroutineOnlySyncsMetadataWithATimeout(t *testing.T) {
+	source, err := os.ReadFile("session_catalog.go")
+	if err != nil {
+		t.Fatal(err)
+	}
+	body := string(source)
+	start := strings.Index(body, "func (a *App) startSessionCatalog(")
+	if start < 0 {
+		t.Fatal("startSessionCatalog not found")
+	}
+	end := strings.Index(body[start+1:], "\nfunc ")
+	if end < 0 {
+		t.Fatal("end of startSessionCatalog not found")
+	}
+	for line := range strings.SplitSeq(body[start:start+1+end], "\n") {
+		if !strings.Contains(line, "syncSessionCatalogMetadata(") {
+			continue
+		}
+		if !strings.Contains(line, "syncSessionCatalogMetadataBounded(") {
+			t.Fatalf("unbounded metadata sync in startSessionCatalog: %s", strings.TrimSpace(line))
+		}
+	}
+}

desktop/session_catalog_recovery_test.go

@@ -41,18 +41,16 @@ func TestProjectNodeFromCatalogTopicFiltersIdleRecoveryCopies(t *testing.T) {
 	sessionOverlays := map[string]catalogRuntimeOverlay{
 		sessionRuntimeKey("/s/open-copy.jsonl"): {open: true},
 	}
-	node, ok := app.projectNodeFromCatalogTopic(topic, map[string]catalogRuntimeOverlay{}, sessionOverlays)
+	node, ok := app.projectNodeFromCatalogTopic(topic, map[string]catalogRuntimeOverlay{}, sessionOverlays, nil)
 	if !ok {
 		t.Fatal("mixed topic should stay visible")
 	}
-	// Parent + open copy remain; idle copy is filtered. Two sessions => children.
-	if len(node.Children) != 2 {
-		t.Fatalf("children = %d, want parent + open recovery copy", len(node.Children))
+	// Ordinary list is always one logical row; open recovery only flips Open.
+	if len(node.Children) != 0 {
+		t.Fatalf("children = %d, want collapsed logical row", len(node.Children))
 	}
-	for _, child := range node.Children {
-		if child.SessionPath == "/s/copy.jsonl" {
-			t.Fatal("idle recovery copy must not appear in project tree children")
-		}
+	if !node.Open {
+		t.Fatal("open recovery member must aggregate onto the logical row")
 	}
 }
 
@@ -64,7 +62,7 @@ func TestProjectNodeFromCatalogTopicHidesRecoveryOnlyIdleTopic(t *testing.T) {
 			{Path: "/s/only.jsonl", Recovered: true, RecoveryCopy: true, Turns: 2, TurnsState: sessioncatalog.TurnsValid, Health: sessioncatalog.HealthOK},
 		},
 	}
-	if _, ok := app.projectNodeFromCatalogTopic(topic, map[string]catalogRuntimeOverlay{}, map[string]catalogRuntimeOverlay{}); ok {
+	if _, ok := app.projectNodeFromCatalogTopic(topic, map[string]catalogRuntimeOverlay{}, map[string]catalogRuntimeOverlay{}, nil); ok {
 		t.Fatal("idle recovery-only topic must be hidden from the ordinary tree")
 	}
 }
@@ -77,7 +75,7 @@ func TestProjectNodeFromCatalogTopicKeepsPinnedRecoveryOnlyTopic(t *testing.T) {
 			{Path: "/s/pinned.jsonl", Recovered: true, RecoveryCopy: true, Turns: 2, TurnsState: sessioncatalog.TurnsValid, Health: sessioncatalog.HealthOK},
 		},
 	}
-	node, ok := app.projectNodeFromCatalogTopic(topic, map[string]catalogRuntimeOverlay{}, map[string]catalogRuntimeOverlay{})
+	node, ok := app.projectNodeFromCatalogTopic(topic, map[string]catalogRuntimeOverlay{}, map[string]catalogRuntimeOverlay{}, nil)
 	if !ok {
 		t.Fatal("pinned recovery-only topic must remain visible")
 	}
@@ -96,7 +94,7 @@ func TestProjectNodeFromCatalogTopicCollapsesWhenOnlyOneVisible(t *testing.T) {
 			{Path: "/s/copy.jsonl", Recovered: true, RecoveryCopy: true, Turns: 2, TurnsState: sessioncatalog.TurnsValid, Health: sessioncatalog.HealthOK},
 		},
 	}
-	node, ok := app.projectNodeFromCatalogTopic(topic, map[string]catalogRuntimeOverlay{}, map[string]catalogRuntimeOverlay{})
+	node, ok := app.projectNodeFromCatalogTopic(topic, map[string]catalogRuntimeOverlay{}, map[string]catalogRuntimeOverlay{}, nil)
 	if !ok {
 		t.Fatal("topic with parent should stay visible")
 	}
@@ -105,6 +103,45 @@ func TestProjectNodeFromCatalogTopicCollapsesWhenOnlyOneVisible(t *testing.T) {
 	}
 }
 
+func TestProjectNodeFromCatalogTopicCollapsesDivergedForksToOne(t *testing.T) {
+	app := &App{tabs: map[string]*WorkspaceTab{}, detachedSessions: map[string]*WorkspaceTab{}}
+	topic := sessioncatalog.TopicRecord{
+		Scope: "global", TopicID: "forks", Title: "WebView", Turns: 5,
+		Sessions: []sessioncatalog.SessionRecord{
+			{Path: "/s/root.jsonl", Turns: 3, TurnsState: sessioncatalog.TurnsValid, Health: sessioncatalog.HealthOK, LastActivityAt: 10},
+			{Path: "/s/fork-a.jsonl", Turns: 5, TurnsState: sessioncatalog.TurnsValid, Health: sessioncatalog.HealthOK,
+				Recovered: true, RecoveryRole: sessioncatalog.RecoveryRoleDiverged, ParentID: "root", RecoveryGroupID: "root", LastActivityAt: 30},
+			{Path: "/s/fork-b.jsonl", Turns: 4, TurnsState: sessioncatalog.TurnsValid, Health: sessioncatalog.HealthOK,
+				Recovered: true, RecoveryRole: sessioncatalog.RecoveryRoleDiverged, ParentID: "root", RecoveryGroupID: "root", LastActivityAt: 40},
+		},
+	}
+	node, ok := app.projectNodeFromCatalogTopic(topic, map[string]catalogRuntimeOverlay{}, map[string]catalogRuntimeOverlay{}, nil)
+	if !ok {
+		t.Fatal("topic with parent should stay visible")
+	}
+	// Parent remains; idle diverged forks hide while the normal root exists.
+	if len(node.Children) != 0 {
+		t.Fatalf("children = %d, want collapsed parent-only row, children=%+v", len(node.Children), node.Children)
+	}
+}
+
+func TestProjectNodeFromCatalogTopicHidesOrphanForkTopicsWhenPreferredElsewhere(t *testing.T) {
+	app := &App{tabs: map[string]*WorkspaceTab{}, detachedSessions: map[string]*WorkspaceTab{}}
+	// Separate topic that only holds a non-preferred diverged fork.
+	topic := sessioncatalog.TopicRecord{
+		Scope: "global", TopicID: "orphan-fork", Title: "WebView",
+		Sessions: []sessioncatalog.SessionRecord{
+			{Path: "/s/fork-only.jsonl", Turns: 2, TurnsState: sessioncatalog.TurnsValid, Health: sessioncatalog.HealthOK,
+				Recovered: true, RecoveryRole: sessioncatalog.RecoveryRoleDiverged, ParentID: "root", RecoveryGroupID: "root"},
+		},
+	}
+	// Workspace preference already chose the parent path for this lineage.
+	preferred := map[string]struct{}{"/s/root.jsonl": {}}
+	if _, ok := app.projectNodeFromCatalogTopic(topic, map[string]catalogRuntimeOverlay{}, map[string]catalogRuntimeOverlay{}, preferred); ok {
+		t.Fatal("orphan non-preferred recovery topic must stay out of the ordinary tree")
+	}
+}
+
 func TestListProjectTopicsSkipsRecoveryOnlyPages(t *testing.T) {
 	ctx := context.Background()
 	catalog, err := sessioncatalog.Open(ctx, sessioncatalog.Options{

desktop/session_catalog_runtime.go

@@ -1,6 +1,7 @@
 package main
 
 import (
+	"context"
 	"errors"
 	"path/filepath"
 	"sort"
@@ -11,6 +12,15 @@ import (
 	"reasonix/internal/sessioncatalog"
 )
 
+// Sidebar reads are bound so a starved connection pool or a slow projection
+// degrades into a stale page the next revision repairs, instead of a Wails call
+// that never returns and a tree that never moves again.
+const sessionCatalogReadTimeout = 10 * time.Second
+
+func (a *App) catalogReadContext() (context.Context, context.CancelFunc) {
+	return context.WithTimeout(a.bootContext(), sessionCatalogReadTimeout)
+}
+
 type catalogRuntimeSnapshot struct {
 	scope         string
 	workspaceRoot string
@@ -172,6 +182,15 @@ func (a *App) metadataProjectTopics(scope, workspaceRoot string) []ProjectNode {
 }
 
 func (a *App) runtimeOnlyProjectTopics(scope, workspaceRoot string) []ProjectNode {
+	nodes, _ := a.runtimeOnlyProjectTopicsWithSessions(scope, workspaceRoot)
+	return nodes
+}
+
+// runtimeOnlyProjectTopicsWithSessions also reports each runtime topic's known
+// session paths so callers can resolve the topics those sessions project onto
+// in the catalog (a restored tab may carry a legacy topic ID for a re-anchored
+// recovery lineage).
+func (a *App) runtimeOnlyProjectTopicsWithSessions(scope, workspaceRoot string) ([]ProjectNode, map[string][]string) {
 	a.mu.RLock()
 	snapshots := []catalogRuntimeSnapshot{}
 	collect := func(tab *WorkspaceTab, open bool) {
@@ -199,11 +218,15 @@ func (a *App) runtimeOnlyProjectTopics(scope, workspaceRoot string) []ProjectNod
 	}
 	a.mu.RUnlock()
 	byTopic := map[string][]catalogRuntimeSnapshot{}
+	sessionsByTopic := map[string][]string{}
 	for _, snapshot := range snapshots {
 		if snapshot.sessionPath == "" && snapshot.ctrl != nil {
 			snapshot.sessionPath = snapshot.ctrl.SessionPath()
 		}
 		byTopic[snapshot.topicID] = append(byTopic[snapshot.topicID], snapshot)
+		if path := strings.TrimSpace(snapshot.sessionPath); path != "" {
+			sessionsByTopic[snapshot.topicID] = append(sessionsByTopic[snapshot.topicID], path)
+		}
 	}
 	topicIDs := make([]string, 0, len(byTopic))
 	for topicID := range byTopic {
@@ -256,7 +279,7 @@ func (a *App) runtimeOnlyProjectTopics(scope, workspaceRoot string) []ProjectNod
 		}
 		out = append(out, node)
 	}
-	return out
+	return out, sessionsByTopic
 }
 
 func (a *App) metadataTopicPage(req ProjectTopicPageRequest) ProjectTopicPage {
@@ -295,7 +318,7 @@ func (a *App) metadataTopicPage(req ProjectTopicPageRequest) ProjectTopicPage {
 	return page
 }
 
-func (a *App) projectNodeFromCatalogTopic(topic sessioncatalog.TopicRecord, topicOverlays, sessionOverlays map[string]catalogRuntimeOverlay) (ProjectNode, bool) {
+func (a *App) projectNodeFromCatalogTopic(topic sessioncatalog.TopicRecord, topicOverlays, sessionOverlays map[string]catalogRuntimeOverlay, preferred map[string]struct{}) (ProjectNode, bool) {
 	kind := "topic"
 	if topic.Scope == "global" {
 		kind = "global_topic"
@@ -307,15 +330,35 @@ func (a *App) projectNodeFromCatalogTopic(topic sessioncatalog.TopicRecord, topi
 		TurnsState: string(topic.TurnsState), Health: string(topic.Health),
 		CreatedAt: topic.CreatedAt, LastActivityAt: topic.LastActivityAt,
 		Pinned: topic.Pinned, Open: overlay.open, Running: overlay.running, Status: overlay.status,
+		// Ordinary tree is zero-config: never surface recovery counts, badges,
+		// or forced-handling status. History "other saved versions" owns that.
 		Children: []ProjectNode{},
 	}
+	// Fall back to topic-local preference when the workspace map is unavailable
+	// so multi-fork topics still collapse instead of listing every replica.
+	localPreferred := preferred
+	if localPreferred == nil {
+		localPreferred = sessioncatalog.PreferredOrdinarySessionPaths(topic.Sessions)
+	}
 	visible := make([]sessioncatalog.SessionRecord, 0, len(topic.Sessions))
 	runtimeSessions := make([]runtimeSessionStatus, 0, len(topic.Sessions))
 	for _, session := range topic.Sessions {
 		sessionOverlay := sessionOverlays[sessionRuntimeKey(session.Path)]
-		// Idle covered recovery copies stay out of the ordinary tree. Open or
-		// running copies remain reachable so the user can still inspect them.
-		if session.RecoveryCopy && !sessionOverlay.open && !sessionOverlay.running {
+		// Aggregate open/running state from every physical member onto the
+		// single logical row — never expand recovery runtimes as children.
+		if sessionOverlay.open {
+			node.Open = true
+		}
+		if sessionOverlay.running {
+			node.Running = true
+			if node.Status == "" {
+				node.Status = sessionOverlay.status
+			}
+		}
+		// 1.23 ordinary-list contract: hide idle covered copies and non-
+		// preferred conflict forks. Open/running recovery is still not a
+		// second row — status is already aggregated above.
+		if !sessioncatalog.OrdinaryTreeSession(session, false, false, localPreferred) {
 			continue
 		}
 		visible = append(visible, session)
@@ -325,50 +368,27 @@ func (a *App) projectNodeFromCatalogTopic(topic sessioncatalog.TopicRecord, topi
 	}
 	summary := topicSummaryFromCatalogTopic(topic, visible)
 	if topicHiddenAsRecoveryOnly(summary, topic.Pinned, append(runtimeSessions, runtimeSessionStatus{
-		open: overlay.open, running: overlay.running,
+		open: overlay.open || node.Open, running: overlay.running || node.Running,
 	})) {
 		return ProjectNode{Children: []ProjectNode{}}, false
 	}
-	// A single effective session collapses to a normal topic row.
-	if len(visible) <= 1 {
-		return node, true
+	// After filtering non-preferred recovery forks, a topic may have nothing
+	// left. Keep pinned/open shells; otherwise drop the empty row.
+	if len(visible) == 0 {
+		if topic.Pinned || overlay.open || overlay.running || node.Open || node.Running {
+			return node, true
+		}
+		return ProjectNode{Children: []ProjectNode{}}, false
 	}
-	diverged := 0
-	for _, session := range visible {
-		if session.RecoveryRole == sessioncatalog.RecoveryRoleDiverged ||
-			(session.Recovered && !session.RecoveryCopy && session.RecoveryRole != sessioncatalog.RecoveryRoleAdopted) {
-			diverged++
-		}
-	}
-	if diverged >= 2 {
-		// Non-destructive choice prompt. The frontend renders the label from
-		// this status so it stays translated.
-		node.Status = topicStatusDivergedRecovery
-	}
-	for _, session := range visible {
-		sessionKind := "session"
-		if topic.Scope == "global" {
-			sessionKind = "global_session"
-		}
-		sessionOverlay := sessionOverlays[sessionRuntimeKey(session.Path)]
-		label := strings.TrimSpace(session.CustomTitle)
-		if label == "" {
-			label = strings.TrimSpace(session.Preview)
-		}
-		if label == "" {
-			label = filepath.Base(session.Path)
-		}
-		node.Children = append(node.Children, ProjectNode{
-			Key: projectSessionNodeKey(topic.Scope, session.Path), Kind: sessionKind,
-			Label: label, Root: topic.WorkspaceRoot, TopicID: topic.TopicID,
-			SessionPath: session.Path, Turns: session.Turns,
-			TurnsState: string(session.TurnsState), Health: string(session.Health),
-			CreatedAt: session.CreatedAt, LastActivityAt: session.LastActivityAt,
-			Open: sessionOverlay.open, Running: sessionOverlay.running, Status: sessionOverlay.status,
-			Recovered: session.Recovered, RecoveryReason: session.RecoveryReason,
-			RecoveryDigest: session.RecoveryDigest, RecoveryParentID: session.ParentID,
-			Children: []ProjectNode{},
-		})
+	// Ordinary list is always one logical row. Multiple normal non-recovery
+	// sessions under one topic also collapse: open/running already aggregated.
+	// History "other saved versions" is the only place physical forks appear.
+	if rep := strings.TrimSpace(topic.RepresentativePath); rep != "" {
+		node.SessionPath = rep
+	} else if path := sessioncatalog.CanonicalSessionPathForTopic(visible, ""); path != "" {
+		node.SessionPath = path
+	} else if len(visible) == 1 {
+		node.SessionPath = visible[0].Path
 	}
 	return node, true
 }
@@ -403,11 +423,100 @@ func topicSummaryFromCatalogTopic(topic sessioncatalog.TopicRecord, visible []se
 }
 
 func (a *App) ListProjectTopics(req ProjectTopicPageRequest) (ProjectTopicPage, error) {
-	out := ProjectTopicPage{Items: []ProjectNode{}}
 	catalog := a.sessionCatalog.Load()
 	if catalog == nil {
+		// Catalog unavailable: use project metadata shells only. Never scan
+		// every recovery JSONL into the ordinary tree (1.23 contract).
+		// While opening/rebuilding with a live catalog, ListTopics already
+		// skips non-ordinary recovery shells so empty pages beat a replica wall.
 		return a.metadataTopicPage(req), nil
 	}
+	page, err := a.catalogTopicPage(catalog, req)
+	if err != nil {
+		return page, err
+	}
+	return a.withLiveTopics(catalog, req, page), nil
+}
+
+// withLiveTopics restores topics the catalog does not (yet) carry. A tab is
+// authoritative for its own existence, while the catalog is a projection that
+// can lag a fresh session, fall behind a stalled writer, or run degraded — and
+// the sidebar must never hide a conversation this app is running. Only an
+// uncursored page merges, so keyset pagination past it stays the catalog's.
+func (a *App) withLiveTopics(catalog *sessioncatalog.Catalog, req ProjectTopicPageRequest, page ProjectTopicPage) ProjectTopicPage {
+	if strings.TrimSpace(req.Cursor) != "" {
+		return page
+	}
+	indexed := make(map[string]bool, len(page.Items))
+	for _, item := range page.Items {
+		indexed[item.TopicID] = true
+	}
+	query := strings.ToLower(strings.TrimSpace(req.Query))
+	live := []ProjectNode{}
+	runtimeNodes, sessionsByTopic := a.runtimeOnlyProjectTopicsWithSessions(req.Scope, req.WorkspaceRoot)
+	ctx, cancel := a.catalogReadContext()
+	defer cancel()
+	for _, node := range runtimeNodes {
+		if indexed[node.TopicID] {
+			continue
+		}
+		// A restored tab may still carry a legacy topic ID for a recovery
+		// session the catalog re-anchored onto the root logical topic. That
+		// logical row already represents the conversation, so a second
+		// runtime-only row would break the one-row ordinary-list contract.
+		if liveTopicProjectedOnPage(ctx, catalog, sessionsByTopic[node.TopicID], indexed) {
+			continue
+		}
+		if query != "" && !strings.Contains(strings.ToLower(node.Label), query) {
+			continue
+		}
+		live = append(live, node)
+	}
+	if len(live) == 0 {
+		return page
+	}
+	f := loadProjectsFile()
+	deleted := map[string]bool{}
+	for _, topicID := range f.DeletedTopics {
+		deleted[topicID] = true
+	}
+	created := loadTopicCreatedAts(topicTitleRoot(req.Scope, req.WorkspaceRoot))
+	kept := page.Items[:0:0]
+	for _, node := range live {
+		if deleted[node.TopicID] {
+			continue
+		}
+		node.CreatedAt = topicCreatedAtForTree(created, node.TopicID)
+		node.LastActivityAt = node.CreatedAt
+		kept = append(kept, node)
+	}
+	page.Items = append(kept, page.Items...)
+	return page
+}
+
+// liveTopicProjectedOnPage reports whether every catalog-known session of a
+// runtime-only topic already projects onto a topic on this page. Any session
+// the catalog has not indexed yet keeps the live row (that is the lag case
+// withLiveTopics exists for), and an off-page projection also keeps it so an
+// open conversation never disappears from the first page.
+func liveTopicProjectedOnPage(ctx context.Context, catalog *sessioncatalog.Catalog, paths []string, indexed map[string]bool) bool {
+	if catalog == nil || len(paths) == 0 {
+		return false
+	}
+	for _, path := range paths {
+		record, ok, err := catalog.GetSession(ctx, path)
+		if err != nil || !ok {
+			return false
+		}
+		if !indexed[record.TopicID] {
+			return false
+		}
+	}
+	return true
+}
+
+func (a *App) catalogTopicPage(catalog *sessioncatalog.Catalog, req ProjectTopicPageRequest) (ProjectTopicPage, error) {
+	out := ProjectTopicPage{Items: []ProjectNode{}}
 	limit := req.Limit
 	if limit <= 0 {
 		limit = sessioncatalog.DefaultLimit
@@ -416,12 +525,20 @@ func (a *App) ListProjectTopics(req ProjectTopicPageRequest) (ProjectTopicPage,
 		limit = sessioncatalog.MaxLimit
 	}
 	topicOverlays, sessionOverlays := a.catalogRuntimeOverlays()
+	ctx, cancel := a.catalogReadContext()
+	defer cancel()
+	// Workspace-wide preference collapses cross-topic recovery replicas that
+	// share a lineage but were indexed as separate topic rows.
+	preferred, prefErr := catalog.PreferredOrdinarySessionPaths(ctx, req.Scope, req.WorkspaceRoot)
+	if prefErr != nil {
+		preferred = nil
+	}
 	cursor := req.Cursor
 	// Keep scanning past pages that are entirely idle recovery copies so the
 	// sidebar never shows an empty "no sessions" state when later pages still
 	// have ordinary topics.
 	for {
-		page, err := catalog.ListTopics(a.bootContext(), sessioncatalog.TopicPageRequest{
+		page, err := catalog.ListTopics(ctx, sessioncatalog.TopicPageRequest{
 			Scope: req.Scope, WorkspaceRoot: req.WorkspaceRoot, Cursor: cursor,
 			Limit: limit, Query: req.Query, TimeFilter: req.TimeFilter,
 		})
@@ -430,7 +547,7 @@ func (a *App) ListProjectTopics(req ProjectTopicPageRequest) (ProjectTopicPage,
 		}
 		out.Revision = page.Revision
 		for i, topic := range page.Items {
-			node, ok := a.projectNodeFromCatalogTopic(topic, topicOverlays, sessionOverlays)
+			node, ok := a.projectNodeFromCatalogTopic(topic, topicOverlays, sessionOverlays, preferred)
 			if !ok {
 				continue
 			}
@@ -462,7 +579,9 @@ func encodeProjectTopicCursor(topic sessioncatalog.TopicRecord) string {
 
 func (a *App) GetTopicSummary(key ProjectTopicKey) (ProjectNode, error) {
 	if catalog := a.sessionCatalog.Load(); catalog != nil {
-		topic, ok, err := catalog.GetTopic(a.bootContext(), sessioncatalog.TopicKey{
+		ctx, cancel := a.catalogReadContext()
+		defer cancel()
+		topic, ok, err := catalog.GetTopic(ctx, sessioncatalog.TopicKey{
 			Scope: key.Scope, WorkspaceRoot: key.WorkspaceRoot, TopicID: key.TopicID,
 		})
 		if err != nil {
@@ -470,7 +589,8 @@ func (a *App) GetTopicSummary(key ProjectTopicKey) (ProjectNode, error) {
 		}
 		if ok {
 			topicOverlays, sessionOverlays := a.catalogRuntimeOverlays()
-			if node, visible := a.projectNodeFromCatalogTopic(topic, topicOverlays, sessionOverlays); visible {
+			preferred, _ := catalog.PreferredOrdinarySessionPaths(ctx, key.Scope, key.WorkspaceRoot)
+			if node, visible := a.projectNodeFromCatalogTopic(topic, topicOverlays, sessionOverlays, preferred); visible {
 				return node, nil
 			}
 			return ProjectNode{Children: []ProjectNode{}}, nil
@@ -572,8 +692,17 @@ func (a *App) catalogSessionPathForTopic(scope, workspaceRoot, topicID string) s
 	if err != nil || !ok || len(topic.Sessions) == 0 {
 		return ""
 	}
+	if canonical := sessioncatalog.CanonicalSessionPathForTopic(topic.Sessions, ""); canonical != "" {
+		return canonical
+	}
+	preferred := sessioncatalog.PreferredOrdinarySessionPaths(topic.Sessions)
 	sort.SliceStable(topic.Sessions, func(i, j int) bool {
-		// Prefer real conversations over idle covered recovery copies.
+		// Prefer ordinary-tree survivors, then real conversations over copies.
+		iPref := sessioncatalog.OrdinaryTreeSession(topic.Sessions[i], false, false, preferred)
+		jPref := sessioncatalog.OrdinaryTreeSession(topic.Sessions[j], false, false, preferred)
+		if iPref != jPref {
+			return iPref
+		}
 		if topic.Sessions[i].RecoveryCopy != topic.Sessions[j].RecoveryCopy {
 			return !topic.Sessions[i].RecoveryCopy
 		}

desktop/tabs.go

@@ -6443,28 +6443,32 @@ func loadTelemetry(path string) tabTelemetrySnapshot {
 // ProjectNode is one node in the sidebar project tree (a project folder or a
 // topic leaf).
 type ProjectNode struct {
-	Key              string        `json:"key"`  // stable key for React
-	Kind             string        `json:"kind"` // "project" | "topic" | "session" | "global_folder" | "global_topic" | "global_session"
-	Label            string        `json:"label"`
-	Root             string        `json:"root,omitempty"` // project workspace root
-	TopicID          string        `json:"topicId,omitempty"`
-	SessionPath      string        `json:"sessionPath,omitempty"`
-	ProjectColor     string        `json:"projectColor,omitempty"`
-	Turns            int           `json:"turns,omitempty"`
-	TurnsState       string        `json:"turnsState,omitempty"`
-	Health           string        `json:"health,omitempty"`
-	CreatedAt        int64         `json:"createdAt,omitempty"`
-	LastActivityAt   int64         `json:"lastActivityAt,omitempty"`
-	Open             bool          `json:"open,omitempty"`
-	Running          bool          `json:"running,omitempty"`
-	Status           string        `json:"status,omitempty"`
-	Pinned           bool          `json:"pinned,omitempty"`
-	Recovered        bool          `json:"recovered,omitempty"`
-	RecoveryReason   string        `json:"recoveryReason,omitempty"`
-	RecoveryDigest   string        `json:"recoveryDigest,omitempty"`
-	RecoveryParentID string        `json:"recoveryParentId,omitempty"`
-	IsolatedWorktree bool          `json:"isolatedWorktree,omitempty"`
-	Children         []ProjectNode `json:"children,omitempty"`
+	Key                          string        `json:"key"`  // stable key for React
+	Kind                         string        `json:"kind"` // "project" | "topic" | "session" | "global_folder" | "global_topic" | "global_session"
+	Label                        string        `json:"label"`
+	Root                         string        `json:"root,omitempty"` // project workspace root
+	TopicID                      string        `json:"topicId,omitempty"`
+	SessionPath                  string        `json:"sessionPath,omitempty"`
+	ProjectColor                 string        `json:"projectColor,omitempty"`
+	Turns                        int           `json:"turns,omitempty"`
+	TurnsState                   string        `json:"turnsState,omitempty"`
+	Health                       string        `json:"health,omitempty"`
+	CreatedAt                    int64         `json:"createdAt,omitempty"`
+	LastActivityAt               int64         `json:"lastActivityAt,omitempty"`
+	Open                         bool          `json:"open,omitempty"`
+	Running                      bool          `json:"running,omitempty"`
+	Status                       string        `json:"status,omitempty"`
+	Pinned                       bool          `json:"pinned,omitempty"`
+	Recovered                    bool          `json:"recovered,omitempty"`
+	RecoveryReason               string        `json:"recoveryReason,omitempty"`
+	RecoveryDigest               string        `json:"recoveryDigest,omitempty"`
+	RecoveryParentID             string        `json:"recoveryParentId,omitempty"`
+	RecoveryState                string        `json:"recoveryState,omitempty"`
+	RecoveryBranchCount          int           `json:"recoveryBranchCount,omitempty"`
+	RecoveryUnresolvedCount      int           `json:"recoveryUnresolvedCount,omitempty"`
+	RecoveryCleanupEligibleCount int           `json:"recoveryCleanupEligibleCount,omitempty"`
+	IsolatedWorktree             bool          `json:"isolatedWorktree,omitempty"`
+	Children                     []ProjectNode `json:"children,omitempty"`
 }
 
 func normalizeTopicStatus(status string) string {

desktop/tabs_topic_test.go

@@ -763,24 +763,35 @@ func TestAmbiguousLegacyRecoverySessionsMigrateIntoTopics(t *testing.T) {
 	}
 
 	app := NewApp()
-	nodes := waitForCatalogTopic(t, app, "global", "", legacySessionTopicID(recovery))
+	// Filename recovery folds into the root ordinary row; History keeps the
+	// physical recovery file reachable as another saved version.
+	app.startSessionCatalog(false)
+	t.Cleanup(func() { app.stopSessionCatalog(time.Second) })
+	nodes := waitForCatalogTreeCondition(t, app, "filename recovery folded into one ordinary row", func(nodes []ProjectNode) bool {
+		for _, folder := range nodes {
+			if folder.Kind != "global_folder" {
+				continue
+			}
+			if len(folder.Children) != 1 {
+				return false
+			}
+			return folder.Children[0].TopicID == legacySessionTopicID(normal)
+		}
+		return false
+	})
 	if len(nodes) != 1 || nodes[0].Kind != "global_folder" {
 		t.Fatalf("project tree = %#v, want global folder", nodes)
 	}
-	if got := len(nodes[0].Children); got != 2 {
-		t.Fatalf("global migrated topics = %d, want both sessions preserved: %#v", got, nodes[0].Children)
+	if got := len(nodes[0].Children); got != 1 {
+		t.Fatalf("global ordinary topics = %d, want 1 folded conversation: %#v", got, nodes[0].Children)
 	}
-	wantTopics := map[string]bool{legacySessionTopicID(normal): true, legacySessionTopicID(recovery): true}
-	for _, node := range nodes[0].Children {
-		delete(wantTopics, node.TopicID)
+	if _, err := os.Stat(recovery); err != nil {
+		t.Fatalf("physical recovery file must remain on disk: %v", err)
 	}
-	if len(wantTopics) != 0 {
-		t.Fatalf("migrated topics missing %v: %#v", wantTopics, nodes[0].Children)
-	}
-	if meta, ok, err := agent.LoadBranchMeta(recovery); err != nil || !ok {
+	if meta, ok, err := agent.LoadBranchMeta(recovery); err != nil {
 		t.Fatalf("load recovery meta: %v", err)
-	} else if strings.TrimSpace(meta.TopicID) == "" {
-		t.Fatal("ambiguous legacy recovery branch was not migrated into a visible topic")
+	} else if ok && strings.TrimSpace(meta.TopicID) == "" && !agent.LooksLikeRecoveryFilename(recovery) {
+		t.Fatal("legacy recovery branch lost both meta topic and filename lineage")
 	}
 }
 

desktop/topic_legacy_migration.go

@@ -365,22 +365,7 @@ func sessionInfoIsUnmodifiedRecoveryCopy(info agent.SessionInfo, parentDir strin
 }
 
 func isAutomaticRecoverySessionPath(path string) bool {
-	id := agent.BranchID(path)
-	idx := strings.LastIndex(id, "-recovery-")
-	if idx <= 0 {
-		return false
-	}
-	suffix := id[idx+len("-recovery-"):]
-	if len(suffix) != 16 {
-		return false
-	}
-	for _, r := range suffix {
-		if (r >= '0' && r <= '9') || (r >= 'a' && r <= 'f') || (r >= 'A' && r <= 'F') {
-			continue
-		}
-		return false
-	}
-	return true
+	return agent.LooksLikeRecoveryFilename(path)
 }
 
 func legacyMigrationTargetForDir(dir string) (scope, workspaceRoot, topicTitleRoot string, ok bool) {

internal/agent/agent.go

@@ -308,12 +308,12 @@ type Agent struct {
 	// for the agent's lifetime and validates proxy calls after resolution.
 	readOnlyExecution bool
 
-	// mutationDependencyBarrier is set for the remainder of a provider tool
-	// batch after any mutating call fails or is blocked. executeOne re-checks
-	// it after proxy resolution so use_capability cannot bypass the barrier by
-	// advertising schema-level ReadOnly()==true. Parallel read-only segments
-	// never set it. Cleared at the start of each executeBatch.
-	mutationDependencyBarrier atomic.Bool
+	// mutationDependencyBarrier records the first durable-state write that
+	// failed or was blocked in the current provider tool batch. executeOne
+	// re-checks it after proxy resolution so use_capability cannot bypass the
+	// barrier by advertising schema-level ReadOnly()==true. The pointed-to
+	// cause is immutable and contains no arguments, paths, or remote addresses.
+	mutationDependencyBarrier atomic.Pointer[mutationBarrierCause]
 
 	// plannerMCPExecution relaxes the strict read-only MCP boundary for the
 	// two-model Planner only: authorized, non-destructive MCP targets may run

internal/agent/branch.go

@@ -48,10 +48,15 @@ type BranchMeta struct {
 	// refuses to fork past SessionRecoveryMaxDepth so a conflict loop cannot
 	// spawn unbounded nested recovery chains (#5993 reached 8 levels). Legacy
 	// recovery metas without the field are treated as depth 1.
-	RecoveryDepth int    `json:"recovery_depth,omitempty"`
-	Revision      int64  `json:"revision,omitempty"`
-	ContentDigest string `json:"content_digest,omitempty"`
-	WriterID      string `json:"writer_id,omitempty"`
+	RecoveryDepth int `json:"recovery_depth,omitempty"`
+	// RecoveryPreferred is a user's explicit choice among genuinely diverged
+	// recovery leaves. It changes the default open target, but never authorizes
+	// deletion and is cleared automatically if that leaf is no longer valid.
+	RecoveryPreferred       bool   `json:"recovery_preferred,omitempty"`
+	RecoveryPreferredDigest string `json:"recovery_preferred_digest,omitempty"`
+	Revision                int64  `json:"revision,omitempty"`
+	ContentDigest           string `json:"content_digest,omitempty"`
+	WriterID                string `json:"writer_id,omitempty"`
 	// SchemaVersion records the BranchMeta version that last wrote the listing
 	// fields (Turns/Preview) FROM the session's content. It is stamped only by the
 	// writers that actually derive those counts — Controller.snapshot's

internal/agent/effect_matrix_test.go

@@ -0,0 +1,41 @@
+package agent
+
+import (
+	"encoding/json"
+	"os"
+	"testing"
+
+	"reasonix/internal/event"
+	"reasonix/internal/provider"
+	"reasonix/internal/tool"
+)
+
+func TestBatchBarrierConsumesSharedCommandEffectMatrix(t *testing.T) {
+	raw, err := os.ReadFile("../shellsafe/testdata/command_effects.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var cases []struct {
+		Name, Command string
+		BatchBarrier  bool
+	}
+	if err := json.Unmarshal(raw, &cases); err != nil {
+		t.Fatal(err)
+	}
+	reg := tool.NewRegistry()
+	reg.Add(fakeTool{name: "bash", readOnly: false})
+	a := New(nil, reg, NewSession(""), Options{}, event.Discard)
+	for _, tc := range cases {
+		t.Run(tc.Name, func(t *testing.T) {
+			args, err := json.Marshal(map[string]string{"command": tc.Command})
+			if err != nil {
+				t.Fatal(err)
+			}
+			call := provider.ToolCall{ID: "failed", Name: "bash", Arguments: string(args)}
+			got := batchCallMutationFailureCause(a, call, toolOutcome{errMsg: "failed"}) != nil
+			if got != tc.BatchBarrier {
+				t.Fatalf("batch barrier for %q = %t, want %t", tc.Command, got, tc.BatchBarrier)
+			}
+		})
+	}
+}

internal/agent/execute_batch.go

@@ -8,11 +8,40 @@ import (
 
 	"reasonix/internal/event"
 	"reasonix/internal/evidence"
-	"reasonix/internal/permission"
 	"reasonix/internal/provider"
 	"reasonix/internal/tool"
 )
 
+// mutationBarrierCause is an immutable, argument-free description of the
+// first durable-state write that failed or was blocked in a tool batch.
+type mutationBarrierCause struct {
+	callID                string
+	toolName              string
+	stateMutation         bool
+	workspaceMutation     bool
+	contentMutation       bool
+	repositoryMutation    bool
+	classificationKnown   bool
+	reason, blockingPhase string
+}
+
+func (c *mutationBarrierCause) message() string {
+	if c == nil {
+		return "blocked: skipped because an earlier modification failed or was blocked in this tool batch. " +
+			"Fix or re-run the failed change first; verification was not executed."
+	}
+	reason := c.reason
+	if reason == "" {
+		reason = "state mutation whose effects cannot be proven read-only"
+	}
+	action := "failed"
+	if c.blockingPhase == "blocked" {
+		action = "was blocked"
+	}
+	return "blocked: skipped because an earlier modification (" + reason + ") " + action + " in this tool batch. " +
+		"Fix or re-run the failed change first; verification was not executed."
+}
+
 // toolOutcome is one tool call's result. output is the first-visible bounded
 // form the model sees; rawOutput is the full original when truncation applied
 // (empty when identical so we avoid double storage). images ride outside text.
@@ -176,9 +205,12 @@ func (a *Agent) executeBatch(ctx context.Context, turn *turnRuntime, calls []pro
 	// blocked, later mutations/verifications in the batch are skipped; read-only
 	// diagnosis still runs. executeOne re-checks after proxy resolution.
 	mutationBatchStop := false
-	a.mutationDependencyBarrier.Store(false)
-	markDependencySkipped := func(start int) {
-		a.mutationDependencyBarrier.Store(true)
+	a.mutationDependencyBarrier.Store(nil)
+	markDependencySkipped := func(start int, cause *mutationBarrierCause) {
+		if cause != nil {
+			a.mutationDependencyBarrier.CompareAndSwap(nil, cause)
+		}
+		cause = a.mutationDependencyBarrier.Load()
 		for j := start; j < len(calls); j++ {
 			if results[j] != "" {
 				continue
@@ -190,8 +222,7 @@ func (a *Agent) executeBatch(ctx context.Context, turn *turnRuntime, calls []pro
 				continue
 			}
 			isVerification := calls[j].Name == "bash" && evidence.IsDeliveryVerificationCommand(bashCommandFromArgs(json.RawMessage(calls[j].Arguments)))
-			msg := "blocked: skipped because an earlier modification in this tool batch failed or was blocked. " +
-				"Fix or re-run the failed change first; verification was not executed."
+			msg := cause.message()
 			var ex *tool.ShellExecution
 			if calls[j].Name == "bash" {
 				ex = &tool.ShellExecution{
@@ -280,16 +311,8 @@ func (a *Agent) executeBatch(ctx context.Context, turn *turnRuntime, calls []pro
 				if results[i] != "" {
 					continue
 				}
-				t, _, ambiguous := a.svc.tools.ResolveCall(calls[i].Name)
-				known := t != nil && len(ambiguous) == 0
-				readOnly := known && t.ReadOnly()
-				if calls[i].Name == "bash" && permission.BashCommandIsReadOnly(json.RawMessage(calls[i].Arguments)) {
-					readOnly = true
-				}
-				isVerification := calls[i].Name == "bash" && evidence.IsDeliveryVerificationCommand(bashCommandFromArgs(json.RawMessage(calls[i].Arguments)))
-				mutates := evidence.ToolCallMutates(calls[i].Name, json.RawMessage(calls[i].Arguments), readOnly)
-				if mutates || isVerification {
-					markDependencySkipped(i)
+				if batchCallStaticallySkippable(a, calls[i]) {
+					markDependencySkipped(i, nil)
 					// markDependencySkipped fills this index; move on.
 					if results[i] != "" {
 						continue
@@ -310,9 +333,9 @@ func (a *Agent) executeBatch(ctx context.Context, turn *turnRuntime, calls []pro
 				break
 			}
 			// Mutation/verification failure barrier for the rest of this batch.
-			if batchCallIsMutatingFailure(a, calls[i], outcomes[i]) {
+			if cause := batchCallMutationFailureCause(a, calls[i], outcomes[i]); cause != nil {
 				mutationBatchStop = true
-				markDependencySkipped(i + 1)
+				markDependencySkipped(i+1, cause)
 			}
 			// After each tool execution, also check if the context was cancelled.
 			// If so, stop executing remaining tools and return immediately so
@@ -385,12 +408,12 @@ func (a *Agent) executeBatch(ctx context.Context, turn *turnRuntime, calls []pro
 	}
 }
 
-// batchCallIsMutatingFailure reports whether a finished call was a mutation
-// (file write / non-readonly bash mutation) that failed or was blocked, so later
-// mutations and verifications in the same batch must not run.
-func batchCallIsMutatingFailure(a *Agent, call provider.ToolCall, o toolOutcome) bool {
+// batchCallMutationFailureCause returns a sanitized effect description when a
+// durable-state mutation failed or was blocked. Verification failures alone do
+// not open the dependency barrier.
+func batchCallMutationFailureCause(a *Agent, call provider.ToolCall, o toolOutcome) *mutationBarrierCause {
 	if o.errMsg == "" && !o.blocked {
-		return false
+		return nil
 	}
 	readOnly := false
 	toolName := call.Name
@@ -411,26 +434,28 @@ func batchCallIsMutatingFailure(a *Agent, call provider.ToolCall, o toolOutcome)
 		toolArgs = o.effective.args
 		readOnly = o.effective.readOnly
 	}
-	if toolName == "bash" && permission.BashCommandIsReadOnly(toolArgs) {
-		readOnly = true
+	effects := evidence.ClassifyToolCall(toolName, toolArgs, readOnly)
+	if toolName == "bash" && evidence.IsDeliveryVerificationCommand(bashCommandFromArgs(toolArgs)) && !effects.StateMutation {
+		return nil
 	}
-	// Verification failures do not open the dependency barrier by themselves —
-	// only a failed modification does.
-	if toolName == "bash" && evidence.IsDeliveryVerificationCommand(bashCommandFromArgs(toolArgs)) {
-		return false
+	if !effects.StateMutation {
+		return nil
 	}
-	// Resolved writers (including MCP targets behind use_capability) count even
-	// when the provider-visible proxy advertised ReadOnly.
-	if o.resolved && !o.resolvedReadOnly {
-		return true
+	phase := "failed"
+	if o.blocked {
+		phase = "blocked"
 	}
-	if evidence.ToolCallMutates(toolName, toolArgs, readOnly) {
-		return true
+	return &mutationBarrierCause{
+		callID:              call.ID,
+		toolName:            toolName,
+		stateMutation:       effects.StateMutation,
+		workspaceMutation:   effects.WorkspaceMutation,
+		contentMutation:     effects.ContentMutation,
+		repositoryMutation:  effects.RepositoryMutation,
+		classificationKnown: effects.Known && known,
+		reason:              effects.Reason,
+		blockingPhase:       phase,
 	}
-	// Fail closed only for a target the host could not classify: a blanket
-	// !readOnly fallback would re-admit the meta tools ToolCallMutates exempts,
-	// letting a failed todo_write block every real edit left in the batch.
-	return !known
 }
 
 // batchCallStaticallySkippable reports whether a remaining call can be marked
@@ -449,14 +474,11 @@ func batchCallStaticallySkippable(a *Agent, call provider.ToolCall) bool {
 		return false
 	}
 	readOnly := t.ReadOnly()
-	if call.Name == "bash" && permission.BashCommandIsReadOnly(json.RawMessage(call.Arguments)) {
-		readOnly = true
-	}
 	isVerification := call.Name == "bash" && evidence.IsDeliveryVerificationCommand(bashCommandFromArgs(json.RawMessage(call.Arguments)))
 	if isVerification {
 		return true
 	}
-	return !readOnly || evidence.ToolCallMutates(call.Name, json.RawMessage(call.Arguments), readOnly)
+	return evidence.ClassifyToolCall(call.Name, json.RawMessage(call.Arguments), readOnly).StateMutation
 }
 
 type toolCallBatch struct {

internal/agent/execute_one.go

@@ -12,55 +12,12 @@ import (
 	"reasonix/internal/instruction"
 	"reasonix/internal/jobs"
 	"reasonix/internal/memory"
-	"reasonix/internal/permission"
 	"reasonix/internal/planmode"
 	"reasonix/internal/provider"
 	"reasonix/internal/sandbox"
 	"reasonix/internal/tool"
 )
 
-// toolCallPlan holds the resolved, policy-checked state for one tool call.
-// Package-private; not shared across goroutines beyond the single executeOne
-// invocation that owns it.
-type toolCallPlan struct {
-	call          provider.ToolCall
-	tool          tool.Tool
-	canonicalName string
-
-	permName     string
-	permArgs     json.RawMessage
-	execTool     tool.Tool
-	execArgs     json.RawMessage
-	evidenceName string
-	evidenceArgs json.RawMessage
-	readOnly     bool
-
-	resolved     tool.ResolvedCall
-	resolvedMeta *tool.ResolvedCall
-
-	mutates                   bool
-	verification              bool
-	planTransition            bool
-	planBefore                string
-	planAfter                 string
-	planDiff                  string
-	planReplacementAuthorized bool
-	recoveryGen               uint64
-
-	runTool              tool.Tool
-	runArgs              json.RawMessage
-	cctx                 context.Context
-	releaseParentWrite   func()
-	releaseMutationWrite func()
-
-	// mutationPath is set when a Previewer described a concrete workspace path
-	// for AfterMutation fingerprint capture (success or failure).
-	mutationPath      string
-	mutationObserved  bool
-	mutationAfterDone bool
-	executed          bool
-}
-
 // executeOne runs a single tool call. It is pure with respect to the event sink
 // — the caller emits ToolDispatch/ToolResult — so it is safe to invoke from
 // parallel goroutines. Stages: parse → policy → prepare → finish.
@@ -157,13 +114,19 @@ func (a *Agent) parseToolCall(ctx context.Context, plan *toolCallPlan) (toolOutc
 	plan.evidenceName = canonicalName
 	plan.evidenceArgs = json.RawMessage(plan.call.Arguments)
 	plan.readOnly = t.ReadOnly()
-	if canonicalName == "bash" && permission.BashCommandIsReadOnly(plan.execArgs) {
-		// Bash is schema-level writer-capable, but the host can resolve a
-		// concrete invocation to read-only after parsing its arguments. Carry
-		// that fact through permission, mutation accounting, evidence, and the
-		// refreshed local tool receipt without changing the provider schema.
-		plan.readOnly = true
-		plan.resolvedMeta = &tool.ResolvedCall{TargetName: canonicalName, ReadOnly: true}
+	if canonicalName == "bash" {
+		var permissionReader bool
+		plan.effects, permissionReader = evidence.ClassifyBashToolCall(plan.execArgs)
+		if permissionReader {
+			// Bash is schema-level writer-capable, but the host can resolve a
+			// concrete invocation to read-only after parsing its arguments. Carry
+			// that fact through permission, mutation accounting, evidence, and the
+			// refreshed local tool receipt without changing the provider schema.
+			plan.readOnly = true
+			plan.resolvedMeta = &tool.ResolvedCall{TargetName: canonicalName, ReadOnly: true}
+		}
+	} else {
+		plan.effects = evidence.ClassifyToolCall(plan.evidenceName, plan.evidenceArgs, plan.readOnly)
 	}
 	return toolOutcome{}, false
 }
@@ -230,18 +193,18 @@ func contextualToolGateOutcome(ctx context.Context, target tool.Tool, name strin
 // read-only diagnosis (resolved ReadOnly with no verification classification)
 // still runs.
 func (a *Agent) applyMutationDependencyBarrier(plan *toolCallPlan) (toolOutcome, bool) {
-	if a == nil || plan == nil || !a.mutationDependencyBarrier.Load() {
+	if a == nil || plan == nil {
+		return toolOutcome{}, false
+	}
+	cause := a.mutationDependencyBarrier.Load()
+	if cause == nil {
 		return toolOutcome{}, false
 	}
 	verification := plan.evidenceName == "bash" && evidence.IsDeliveryVerificationCommand(bashCommandFromArgs(plan.evidenceArgs))
-	// Prefer the post-gate mutates flag; fall back to !readOnly so a resolved
-	// writer proxy cannot claim non-mutation by skipping ToolCallMutates.
-	mutates := plan.mutates || !plan.readOnly
-	if !mutates && !verification {
+	if !plan.effects.StateMutation && !verification {
 		return toolOutcome{}, false
 	}
-	msg := "blocked: skipped because an earlier modification in this tool batch failed or was blocked. " +
-		"Fix or re-run the failed change first; verification was not executed."
+	msg := cause.message()
 	var ex *tool.ShellExecution
 	// Structured shell metadata only for bash cards; other tools keep plain text.
 	if plan.evidenceName == "bash" || plan.call.Name == "bash" {
@@ -315,6 +278,7 @@ func (a *Agent) applyPlanModeAndProxy(ctx context.Context, plan *toolCallPlan) (
 			return outcome, true
 		}
 		plan.readOnly = rc.ReadOnly
+		plan.classifyEffects()
 		if outcome, blocked := a.readOnlyExecutionBlock(t, &rc); blocked {
 			return outcome, true
 		}
@@ -453,7 +417,7 @@ func (a *Agent) applyDeliveryPolicyGates(turn *turnRuntime, plan *toolCallPlan)
 		}, true
 	}
 
-	plan.mutates = evidence.ToolCallMutates(plan.evidenceName, plan.evidenceArgs, plan.readOnly)
+	plan.classifyEffects()
 	persistentWorkflowCall := turn.deliveryPersistentExpected && !turn.deliveryMutationExpected && plan.evidenceName == "remember"
 	if a.deliveryProfile && !persistentWorkflowCall && evidence.ToolCallRequiresDeliveryCriteria(plan.evidenceName, plan.evidenceArgs, plan.readOnly) && !turn.deliveryCriteriaEstablished {
 		return toolOutcome{
@@ -462,7 +426,7 @@ func (a *Agent) applyDeliveryPolicyGates(turn *turnRuntime, plan *toolCallPlan)
 			errMsg:  "blocked: delivery acceptance criteria required",
 		}, true
 	}
-	if a.deliveryProfile && !persistentWorkflowCall && plan.mutates && !a.hasActiveCanonicalTodo() {
+	if a.deliveryProfile && !persistentWorkflowCall && plan.effects.ContentMutation && !a.hasActiveCanonicalTodo() {
 		return toolOutcome{
 			output:  "blocked: delivery-first mode requires every state change to belong to the current in_progress todo. Preserve the completed todo prefix, append a concrete new item if more work was discovered, mark that item in_progress with todo_write, then retry this mutation.",
 			blocked: true,
@@ -488,7 +452,7 @@ func (a *Agent) applyRecoveryAndPermission(ctx context.Context, plan *toolCallPl
 		plan.recoveryGen = ctrl.Generation()
 		episodeStopped = ctrl.EpisodeStopped(a.recovery.taskID)
 	}
-	if a.svc.recoveryGate != nil && (plan.mutates || plan.verification || plan.planTransition || episodeStopped) {
+	if a.svc.recoveryGate != nil && (plan.effects.StateMutation || plan.verification || plan.planTransition || episodeStopped) {
 		subject := recoverySubject(plan.evidenceName, plan.evidenceArgs)
 		if plan.planTransition {
 			subject = "Update the active execution plan"
@@ -598,7 +562,7 @@ func (a *Agent) prepareToolExecution(ctx context.Context, plan *toolCallPlan) (t
 	// concurrent and avoids holding the workspace during an approval prompt while
 	// still covering every write-side action that follows authorization.
 	// Lazy workspace lease on the first real writer for every role setting.
-	if plan.mutates && a.svc.workspaceLease != nil {
+	if plan.effects.WorkspaceMutation && a.svc.workspaceLease != nil {
 		if err := a.svc.workspaceLease.AcquireWrite(ctx); err != nil {
 			return toolOutcome{
 				output:  fmt.Sprintf("blocked: the workspace did not become available for writing: %v", err),
@@ -624,7 +588,7 @@ func (a *Agent) prepareToolExecution(ctx context.Context, plan *toolCallPlan) (t
 	// check-before-write TOCTOU windows. Dynamic Economy/MCP tools are covered
 	// here after registry lookup without schema-changing wrappers.
 	// executeOne defers plan.releaseParentWrite so every return path releases.
-	if releaseParentWrite, perr := a.reserveParentWrite(plan.runTool, plan.runArgs, plan.readOnly); perr != nil {
+	if releaseParentWrite, perr := a.reserveParentWrite(plan.runTool, plan.runArgs, !plan.effects.WorkspaceMutation); perr != nil {
 		return toolOutcome{
 			output:  "blocked: " + perr.Error(),
 			blocked: true,
@@ -636,7 +600,7 @@ func (a *Agent) prepareToolExecution(ctx context.Context, plan *toolCallPlan) (t
 	// Acquire the checkpoint barrier before preimage capture and any hook. It is
 	// held through post hooks and AfterMutation so rewind cannot interleave with
 	// writer-side user code.
-	if !plan.readOnly && a.svc.mutationObserver != nil && a.svc.mutationObserver.Store() != nil {
+	if plan.effects.WorkspaceMutation && a.svc.mutationObserver != nil && a.svc.mutationObserver.Store() != nil {
 		barrier := a.svc.mutationObserver.Store().Barrier()
 		if err := barrier.EnterWrite(); err != nil {
 			return toolOutcome{output: "blocked: " + err.Error(), blocked: true, errMsg: "blocked: mutation barrier unavailable"}, true
@@ -648,7 +612,7 @@ func (a *Agent) prepareToolExecution(ctx context.Context, plan *toolCallPlan) (t
 	// still finalizes the fingerprint on every return path. Built-in
 	// Previewers get precise paths (complete coverage). Bash / opaque MCP
 	// writers record explicit coverage gaps instead of guessing targets.
-	if !plan.readOnly {
+	if plan.effects.WorkspaceMutation {
 		a.observeBeforeMutation(ctx, plan)
 		plan.mutationObserved = plan.mutationPath != ""
 		if toolHooksMayMutateWorkspace(a.svc.hooks) && a.svc.mutationObserver != nil {
@@ -746,7 +710,7 @@ func (a *Agent) finishToolExecution(ctx context.Context, plan *toolCallPlan) too
 	permArgs := plan.permArgs
 	evidenceName := plan.evidenceName
 	evidenceArgs := plan.evidenceArgs
-	mutates := plan.mutates
+	mutates := plan.effects.StateMutation
 	recoveryGen := plan.recoveryGen
 
 	var result string
@@ -800,7 +764,6 @@ func (a *Agent) finishToolExecution(ctx context.Context, plan *toolCallPlan) too
 	if msg, refused := tool.BlockedMessage(err); refused {
 		return a.blockedToolOutcome(plan, msg)
 	}
-	a.recordToolReceipts(plan, result, execution, err)
 	// Track skill/capability outcomes for Delivery gates.
 	a.noteCapabilityInvocation(call.Name, json.RawMessage(call.Arguments), err)
 	// Success and failure hooks observe the result after the tool ran. Use the
@@ -814,8 +777,7 @@ func (a *Agent) finishToolExecution(ctx context.Context, plan *toolCallPlan) too
 	}
 	// Always re-read after post hooks — partial writes and hook side effects can
 	// change the previewed path even when the concrete tool returned an error.
-	a.observeAfterMutation(plan)
-	plan.mutationAfterDone = true
+	a.finalizeObservedToolReceipts(plan, result, execution, err)
 	if a.svc.recoveryGate != nil {
 		a.observeRecoveryResult(ctx, evidenceName, evidenceArgs, readOnly, mutates, result, err, false, false, recoveryGen)
 	}
@@ -905,13 +867,19 @@ func (a *Agent) observeBeforeMutation(ctx context.Context, plan *toolCallPlan) {
 
 // observeAfterMutation records the after fingerprint when a concrete path was
 // known before execution, regardless of tool success or failure.
-func (a *Agent) observeAfterMutation(plan *toolCallPlan) {
+func (a *Agent) observeAfterMutation(plan *toolCallPlan) bool {
 	if a == nil || plan == nil || plan.mutationPath == "" || a.svc.mutationObserver == nil {
-		return
+		return false
 	}
 	toolName := plan.evidenceName
 	if toolName == "" {
 		toolName = plan.call.Name
 	}
-	a.svc.mutationObserver.AfterMutation(plan.mutationPath, toolName)
+	changed := a.svc.mutationObserver.AfterMutation(plan.mutationPath, toolName)
+	if changed {
+		plan.effects.StateMutation = true
+		plan.effects.WorkspaceMutation = true
+		plan.effects.ContentMutation = true
+	}
+	return changed
 }

internal/agent/guards_test.go

@@ -442,12 +442,18 @@ func TestExecuteBatchPublishesWorkspaceMutationBeforeLaterToolCompletes(t *testi
 
 func TestWorkspaceMutationClassifierTreatsGitCommitAsGitMetadata(t *testing.T) {
 	mutation, ok := workspaceMutationForCall("call", "bash", json.RawMessage(`{"command":"git commit -m test"}`), false)
-	if !ok || !mutation.GitMeta || !mutation.WorkingTree || !mutation.AllPaths {
+	if !ok || !mutation.GitMeta || mutation.Content || mutation.WorkingTree || mutation.Tree || !mutation.AllPaths {
 		t.Fatalf("git commit workspace invalidation = %+v, ok=%v", mutation, ok)
 	}
-	mutation, ok = workspaceMutationForCall("call", "bash", json.RawMessage(`{"command":"go test ./..."}`), false)
-	if !ok || mutation.GitMeta {
-		t.Fatalf("ordinary bash workspace invalidation refreshed git metadata: %+v, ok=%v", mutation, ok)
+	mutation, ok = workspaceMutationForCall("call", "bash", json.RawMessage(`{"command":"git commit -am test"}`), false)
+	if !ok || !mutation.GitMeta || !mutation.Content || !mutation.WorkingTree || !mutation.Tree {
+		t.Fatalf("content-writing git commit invalidation = %+v, ok=%v", mutation, ok)
+	}
+	if mutation, ok = workspaceMutationForCall("call", "bash", json.RawMessage(`{"command":"go test ./..."}`), false); ok {
+		t.Fatalf("ordinary verifier invalidated durable workspace state: %+v", mutation)
+	}
+	if mutation, ok = workspaceMutationForCall("call", "bash", json.RawMessage(`{"command":"date --set tomorrow"}`), false); ok {
+		t.Fatalf("host-only state write invalidated the workspace: %+v", mutation)
 	}
 	if mutation, ok = workspaceMutationForCall("call", "remember", json.RawMessage(`{"name":"preference"}`), false); ok {
 		t.Fatalf("host-only memory write invalidated the workspace: %+v", mutation)

internal/agent/plan_transition_diff.go

@@ -59,13 +59,13 @@ func (a *Agent) recoveryProposal(plan *toolCallPlan, episodeID, subject, preview
 		Subject:        subject,
 		Preview:        preview,
 		ReadOnly:       plan.readOnly,
-		Mutates:        plan.mutates,
+		Mutates:        plan.effects.StateMutation,
 		Verification:   plan.verification,
 		PlanTransition: plan.planTransition,
 		// The existing rule asks whether a retry drifts from the call that
 		// failed. This asks the question the user actually approved an answer
 		// to: is this write outside the plan they agreed on.
-		ExpandedScope: plan.mutates && a.mutationEscapesPlan(plan.evidenceName, plan.evidenceArgs),
+		ExpandedScope: plan.effects.StateMutation && a.mutationEscapesPlan(plan.evidenceName, plan.evidenceArgs),
 		PlanBefore:    plan.planBefore,
 		PlanAfter:     plan.planAfter,
 		PlanDiff:      plan.planDiff,

internal/agent/read_novelty_guard_test.go

@@ -0,0 +1,103 @@
+package agent
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"strings"
+	"testing"
+
+	"reasonix/internal/event"
+	"reasonix/internal/provider"
+	"reasonix/internal/tool"
+)
+
+// grepNoveltyProbe mirrors the real grep tool's receipt shape: read-only,
+// path-scoped, and carrying its question in an argument rather than the path.
+type grepNoveltyProbe struct{}
+
+func (grepNoveltyProbe) Name() string        { return "grep" }
+func (grepNoveltyProbe) Description() string { return "search" }
+func (grepNoveltyProbe) Schema() json.RawMessage {
+	return json.RawMessage(`{"type":"object","properties":{"pattern":{"type":"string"},"path":{"type":"string"}},"required":["pattern"]}`)
+}
+func (grepNoveltyProbe) ReadOnly() bool { return true }
+func (grepNoveltyProbe) Execute(context.Context, json.RawMessage) (string, error) {
+	return "internal/agent/agent.go:120: match\n", nil
+}
+
+// runNoveltyRounds executes one call per round and returns the guard text each
+// round received, indexed from round 1.
+func runNoveltyRounds(t *testing.T, calls []provider.ToolCall) []string {
+	t.Helper()
+	reg := tool.NewRegistry()
+	reg.Add(readProbe{})
+	reg.Add(grepNoveltyProbe{})
+	a := New(nil, reg, NewSession(""), Options{}, event.Discard)
+	a.resetTurnEvidence()
+
+	fired := make([]string, len(calls)+1)
+	for i, call := range calls {
+		batch := a.executeBatch(context.Background(), &a.turn, []provider.ToolCall{call})
+		if out := batch.results[0]; strings.Contains(out, "[progress guard]") {
+			fired[i+1] = out[strings.Index(out, "[progress guard]"):]
+		}
+	}
+	return fired
+}
+
+func assertNoStopTier(t *testing.T, fired []string, what string) {
+	t.Helper()
+	for round, text := range fired {
+		if strings.Contains(text, "produce your final answer now") {
+			t.Errorf("%s: round %d was told it produced no new evidence and ordered to answer", what, round)
+		}
+	}
+}
+
+// Ten searches of one package, a different pattern each time. Every round
+// returns information the turn did not have; keying novelty on the path alone
+// scored nine of them as repeats and stopped the turn at round 7.
+func TestGrepWithNewPatternsNoLongerTripsTheGuard(t *testing.T) {
+	var calls []provider.ToolCall
+	for i, p := range []string{"Compose", "Receipt", "Ledger", "progressGuard", "applyEBM", "Delivery", "ToolCall", "Session", "compact", "readiness"} {
+		calls = append(calls, provider.ToolCall{
+			ID: fmt.Sprintf("g%d", i), Name: "grep",
+			Arguments: fmt.Sprintf(`{"pattern":%q,"path":"internal/agent"}`, p),
+		})
+	}
+	assertNoStopTier(t, runNoveltyRounds(t, calls), "ten distinct searches")
+}
+
+// Paging through one long file: distinct windows, one path.
+func TestPagingOneFileNoLongerTripsTheGuard(t *testing.T) {
+	var calls []provider.ToolCall
+	for i := range 10 {
+		calls = append(calls, provider.ToolCall{
+			ID: fmt.Sprintf("r%d", i), Name: "read_file",
+			Arguments: fmt.Sprintf(`{"path":"internal/agent/agent.go","offset":%d,"limit":300}`, i*300),
+		})
+	}
+	assertNoStopTier(t, runNoveltyRounds(t, calls), "paging one file")
+}
+
+// The discriminator stays intact: re-asking the identical question is still a
+// repeat, and the ladder still escalates on it.
+func TestIdenticalReadsStillEscalate(t *testing.T) {
+	var calls []provider.ToolCall
+	for i := range progressStopStreak + 2 {
+		calls = append(calls, provider.ToolCall{
+			ID: fmt.Sprintf("s%d", i), Name: "read_file", Arguments: `{"path":"same.go"}`,
+		})
+	}
+	fired := runNoveltyRounds(t, calls)
+	stopped := false
+	for _, text := range fired {
+		if strings.Contains(text, "produce your final answer now") {
+			stopped = true
+		}
+	}
+	if !stopped {
+		t.Fatal("re-reading one path must still reach the stop tier")
+	}
+}

internal/agent/recovery_filename.go

@@ -0,0 +1,80 @@
+package agent
+
+import (
+	"path/filepath"
+	"strings"
+)
+
+// RecoveryFilenameParentID recognizes legacy automatic recovery files named
+// <stem>-recovery-<16 hex>.jsonl when meta is missing or incomplete. The parent
+// ID is the stem before the final -recovery-<hex> suffix (not a content proof).
+func RecoveryFilenameParentID(path string) (string, bool) {
+	id := BranchID(path)
+	parent, ok := peelRecoveryFilenameSuffix(id)
+	if !ok {
+		return "", false
+	}
+	return parent, true
+}
+
+// RecoveryFilenameRootID peels nested -recovery-<16 hex> suffixes to the
+// non-recovery stem used as a stable recovery-group key for old files.
+func RecoveryFilenameRootID(path string) (string, bool) {
+	id := BranchID(path)
+	root, ok := peelRecoveryFilenameSuffix(id)
+	if !ok {
+		return "", false
+	}
+	for {
+		next, nested := peelRecoveryFilenameSuffix(root)
+		if !nested {
+			break
+		}
+		root = next
+	}
+	if strings.TrimSpace(root) == "" {
+		return "", false
+	}
+	return root, true
+}
+
+// LooksLikeRecoveryFilename reports whether the path follows the automatic
+// recovery naming convention used before meta always carried Recovered=true.
+func LooksLikeRecoveryFilename(path string) bool {
+	_, ok := peelRecoveryFilenameSuffix(BranchID(path))
+	return ok
+}
+
+func peelRecoveryFilenameSuffix(id string) (string, bool) {
+	id = strings.TrimSpace(id)
+	const marker = "-recovery-"
+	index := strings.LastIndex(id, marker)
+	if index <= 0 {
+		return "", false
+	}
+	suffix := id[index+len(marker):]
+	if len(suffix) != 16 || !isLowerHex(suffix) {
+		return "", false
+	}
+	parent := strings.TrimSpace(id[:index])
+	if parent == "" || parent == "." || filepath.Base(parent) != parent {
+		return "", false
+	}
+	return parent, true
+}
+
+func isLowerHex(value string) bool {
+	if value == "" {
+		return false
+	}
+	for _, r := range value {
+		switch {
+		case r >= '0' && r <= '9':
+		case r >= 'a' && r <= 'f':
+		case r >= 'A' && r <= 'F':
+		default:
+			return false
+		}
+	}
+	return true
+}

internal/agent/recovery_filename_test.go

@@ -0,0 +1,21 @@
+package agent
+
+import "testing"
+
+func TestRecoveryFilenameParentAndRoot(t *testing.T) {
+	t.Parallel()
+	parent, ok := RecoveryFilenameParentID("/tmp/session-recovery-aabbccddeeff0011.jsonl")
+	if !ok || parent != "session" {
+		t.Fatalf("parent = %q ok=%v", parent, ok)
+	}
+	root, ok := RecoveryFilenameRootID("/tmp/session-recovery-aabbccddeeff0011.jsonl")
+	if !ok || root != "session" {
+		t.Fatalf("root = %q ok=%v", root, ok)
+	}
+	if LooksLikeRecoveryFilename("/tmp/session.jsonl") {
+		t.Fatal("plain session should not match")
+	}
+	if !LooksLikeRecoveryFilename("/tmp/session-recovery-AABBCCDDEEFF0011.jsonl") {
+		t.Fatal("uppercase hex should match")
+	}
+}

internal/agent/recovery_gc.go

@@ -7,10 +7,12 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"sort"
 	"strings"
 	"time"
 
 	"reasonix/internal/fileutil"
+	"reasonix/internal/provider"
 	"reasonix/internal/store"
 )
 
@@ -88,18 +90,109 @@ func RecoveryBranchCoveredByParent(path, parentDir string) bool {
 // history stored in covered. It is intentionally conservative for catalog
 // canonical promotion: repaired or damaged loads cannot authorize a redirect.
 func SessionContentCovers(coveringPath, coveredPath string) bool {
-	covering, err := LoadSession(coveringPath)
-	if err != nil || covering == nil || covering.normalizedDirty || covering.eventLogDamaged {
+	covering, ok := LoadSessionContentSnapshot(coveringPath)
+	if !ok {
 		return false
 	}
-	covered, err := LoadSession(coveredPath)
-	if err != nil || covered == nil || covered.normalizedDirty || covered.eventLogDamaged {
+	covered, ok := LoadSessionContentSnapshot(coveredPath)
+	return ok && covering.Covers(covered)
+}
+
+// SetRecoveryPreferred records exactly one explicit preferred leaf. It clears
+// old choices first, so interruption can only fall back to an unresolved group;
+// it can never leave two canonical choices.
+func SetRecoveryPreferred(paths []string, chosenPath string) error {
+	chosenPath = canonicalSessionSavePath(chosenPath)
+	if chosenPath == "" {
+		return fmt.Errorf("empty preferred recovery path")
+	}
+	unique := map[string]struct{}{}
+	for _, path := range paths {
+		path = canonicalSessionSavePath(path)
+		if path != "" {
+			unique[path] = struct{}{}
+		}
+	}
+	if _, ok := unique[chosenPath]; !ok {
+		return fmt.Errorf("preferred recovery path is outside the lineage")
+	}
+	ordered := make([]string, 0, len(unique))
+	for path := range unique {
+		meta, ok, err := LoadBranchMeta(path)
+		if err != nil || !ok || !meta.Recovered {
+			return fmt.Errorf("invalid recovery lineage member")
+		}
+		ordered = append(ordered, path)
+	}
+	sort.Strings(ordered)
+	for _, path := range ordered {
+		if err := UpdateBranchMeta(path, false, func(meta *BranchMeta) error {
+			meta.RecoveryPreferred = false
+			meta.RecoveryPreferredDigest = ""
+			return nil
+		}); err != nil {
+			return err
+		}
+	}
+	chosen, err := LoadSession(chosenPath)
+	if err != nil || chosen == nil || chosen.normalizedDirty || chosen.eventLogDamaged {
+		return fmt.Errorf("could not fingerprint preferred recovery branch")
+	}
+	digest, err := digestSessionMessages(chosen.Snapshot())
+	if err != nil {
+		return err
+	}
+	return UpdateBranchMeta(chosenPath, false, func(meta *BranchMeta) error {
+		if !meta.Recovered {
+			return fmt.Errorf("preferred session is not a recovery branch")
+		}
+		meta.RecoveryPreferred = true
+		meta.RecoveryPreferredDigest = digestString(digest)
+		return nil
+	})
+}
+
+// RecoveryPreferenceCurrent proves that the branch still has the exact content
+// the user selected. Continued or externally edited branches fall back to an
+// unresolved lineage until the user chooses again.
+func RecoveryPreferenceCurrent(path string, meta BranchMeta) bool {
+	if !meta.RecoveryPreferred || strings.TrimSpace(meta.RecoveryPreferredDigest) == "" {
 		return false
 	}
-	coveringMessages := covering.Snapshot()
-	coveredMessages := covered.Snapshot()
-	return messagesHavePrefix(coveringMessages, coveredMessages) ||
-		messagesHavePrefixWithCompatibleSystem(coveringMessages, coveredMessages)
+	session, err := LoadSession(path)
+	if err != nil || session == nil || session.normalizedDirty || session.eventLogDamaged {
+		return false
+	}
+	digest, err := digestSessionMessages(session.Snapshot())
+	return err == nil && digestString(digest) == strings.TrimSpace(meta.RecoveryPreferredDigest)
+}
+
+// SessionContentSnapshot is an immutable, validated transcript projection used
+// by the catalog. Its messages stay private so callers cannot accidentally use
+// a classification read as a mutable Session.
+type SessionContentSnapshot struct {
+	messages []provider.Message
+}
+
+// LoadSessionContentSnapshot loads one transcript once for lineage analysis.
+// Dirty normalization and damaged event logs fail closed: neither may prove a
+// canonical branch or authorize cleanup.
+func LoadSessionContentSnapshot(path string) (SessionContentSnapshot, bool) {
+	session, err := LoadSession(path)
+	if err != nil || session == nil || session.normalizedDirty || session.eventLogDamaged {
+		return SessionContentSnapshot{}, false
+	}
+	return SessionContentSnapshot{messages: session.Snapshot()}, true
+}
+
+// Len is used only to discard candidates that cannot cover the longest member.
+func (s SessionContentSnapshot) Len() int { return len(s.messages) }
+
+// Covers reports whether s contains all content in covered as a compatible
+// prefix. Both snapshots have already passed the conservative load checks.
+func (s SessionContentSnapshot) Covers(covered SessionContentSnapshot) bool {
+	return messagesHavePrefix(s.messages, covered.messages) ||
+		messagesHavePrefixWithCompatibleSystem(s.messages, covered.messages)
 }
 
 // TryAcquireRecoveryParentGuard verifies that a recovery branch is covered by
@@ -238,6 +331,101 @@ func TrashCoveredRecoveryBranch(path, parentDir string) error {
 	return trashCoveredRecoveryBranch(path, parentDir, false)
 }
 
+// TrashRecoveryBranchCoveredBy moves path to recoverable trash when canonical
+// contains its complete transcript. Unlike TrashCoveredRecoveryBranch this is
+// lineage-aware: legacy recovery storms form chains, so an adopted leaf may
+// cover an ancestor even though that ancestor's immediate parent does not cover
+// it. Both transcripts are held behind removal guards while coverage is proved.
+func TrashRecoveryBranchCoveredBy(path, canonicalPath, parentDir string) error {
+	path = filepath.Clean(strings.TrimSpace(path))
+	canonicalPath = filepath.Clean(strings.TrimSpace(canonicalPath))
+	parentDir = filepath.Clean(strings.TrimSpace(parentDir))
+	if path == "." || canonicalPath == "." || parentDir == "." || path == canonicalPath ||
+		filepath.Dir(path) != parentDir || filepath.Dir(canonicalPath) != parentDir {
+		return ErrRecoveryBranchNotCovered
+	}
+	meta, ok, err := LoadBranchMeta(path)
+	if err != nil || !ok || !meta.Recovered {
+		return ErrRecoveryBranchNotCovered
+	}
+	paths := []string{path, canonicalPath}
+	sort.Strings(paths)
+	guards := make(map[string]*SessionRemovalGuard, len(paths))
+	for _, guardedPath := range paths {
+		guard, guardErr := TryAcquireSessionRemovalGuard(guardedPath)
+		if guardErr != nil {
+			for _, held := range guards {
+				held.Release()
+			}
+			return guardErr
+		}
+		guards[guardedPath] = guard
+	}
+	defer func() {
+		for _, guard := range guards {
+			guard.Release()
+		}
+	}()
+	if !SessionContentCovers(canonicalPath, path) {
+		return ErrRecoveryBranchNotCovered
+	}
+	key := filepath.Base(path)
+	if !validRecoveryTrashKey(key) {
+		return fmt.Errorf("invalid recovery session path")
+	}
+	stageDir, err := reserveRecoveryTrashStage(parentDir)
+	if err != nil {
+		return err
+	}
+	if err := prepareRecoveryTrashStage(path, key, stageDir); err != nil {
+		return err
+	}
+	return finishRecoveryTrashStage(parentDir, path, key, stageDir, guards[path])
+}
+
+// ReparentRecoveryCanonical shortens a proved recovery chain to root ->
+// canonical without rewriting either transcript. This preserves discovery for
+// older versions after covered intermediate branches are moved to trash.
+func ReparentRecoveryCanonical(canonicalPath, rootID, parentDir string) error {
+	canonicalPath = filepath.Clean(strings.TrimSpace(canonicalPath))
+	parentDir = filepath.Clean(strings.TrimSpace(parentDir))
+	rootID = strings.TrimSpace(rootID)
+	rootPath := filepath.Join(parentDir, rootID+".jsonl")
+	if canonicalPath == "." || parentDir == "." || rootID == "" || filepath.Base(rootID) != rootID ||
+		filepath.Dir(canonicalPath) != parentDir || canonicalPath == rootPath {
+		return ErrRecoveryBranchNotCovered
+	}
+	paths := []string{canonicalPath, rootPath}
+	sort.Strings(paths)
+	guards := make([]*SessionRemovalGuard, 0, len(paths))
+	for _, path := range paths {
+		guard, err := TryAcquireSessionRemovalGuard(path)
+		if err != nil {
+			for _, held := range guards {
+				held.Release()
+			}
+			return err
+		}
+		guards = append(guards, guard)
+	}
+	defer func() {
+		for _, guard := range guards {
+			guard.Release()
+		}
+	}()
+	if !SessionContentCovers(canonicalPath, rootPath) {
+		return ErrRecoveryBranchNotCovered
+	}
+	return UpdateBranchMeta(canonicalPath, false, func(meta *BranchMeta) error {
+		if !meta.Recovered {
+			return ErrRecoveryBranchNotCovered
+		}
+		meta.ParentID = rootID
+		meta.RecoveryDepth = 1
+		return nil
+	})
+}
+
 // TrashReclaimableRecoveryBranch is the background-GC variant. In addition to
 // the same atomic coverage proof, it requires the branch to remain idle for the
 // full grace period.

internal/agent/recovery_gc_test.go

@@ -277,6 +277,100 @@ func TestTrashReclaimableRecoveryBranchUsesRecoverableDesktopLayout(t *testing.T
 	}
 }
 
+func TestTrashRecoveryBranchCoveredByCanonicalCompactsLegacyChain(t *testing.T) {
+	dir := t.TempDir()
+	rootPath := filepath.Join(dir, "root.jsonl")
+	ancestorPath := filepath.Join(dir, "ancestor.jsonl")
+	canonicalPath := filepath.Join(dir, "canonical.jsonl")
+	root := NewSession("sys")
+	root.Add(provider.Message{Role: provider.RoleUser, Content: "root"})
+	if err := root.Save(rootPath); err != nil {
+		t.Fatal(err)
+	}
+	ancestor := NewSession("")
+	ancestor.Replace(root.Snapshot())
+	ancestor.Add(provider.Message{Role: provider.RoleAssistant, Content: "ancestor"})
+	if err := ancestor.Save(ancestorPath); err != nil {
+		t.Fatal(err)
+	}
+	if err := SaveBranchMetaPreserveUpdated(ancestorPath, BranchMeta{ID: "ancestor", Recovered: true, ParentID: "root", RecoveryDepth: 1}); err != nil {
+		t.Fatal(err)
+	}
+	canonical := NewSession("")
+	canonical.Replace(ancestor.Snapshot())
+	canonical.Add(provider.Message{Role: provider.RoleUser, Content: "continued"})
+	if err := canonical.Save(canonicalPath); err != nil {
+		t.Fatal(err)
+	}
+	if err := SaveBranchMetaPreserveUpdated(canonicalPath, BranchMeta{ID: "canonical", Recovered: true, ParentID: "ancestor", RecoveryDepth: 2}); err != nil {
+		t.Fatal(err)
+	}
+	if err := ReparentRecoveryCanonical(canonicalPath, "root", dir); err != nil {
+		t.Fatalf("ReparentRecoveryCanonical: %v", err)
+	}
+	if err := TrashRecoveryBranchCoveredBy(ancestorPath, canonicalPath, dir); err != nil {
+		t.Fatalf("TrashRecoveryBranchCoveredBy: %v", err)
+	}
+	meta, ok, err := LoadBranchMeta(canonicalPath)
+	if err != nil || !ok || meta.ParentID != "root" || meta.RecoveryDepth != 1 {
+		t.Fatalf("canonical meta = %+v ok=%v err=%v", meta, ok, err)
+	}
+	if _, err := os.Stat(rootPath); err != nil {
+		t.Fatalf("root was removed: %v", err)
+	}
+	if _, err := os.Stat(canonicalPath); err != nil {
+		t.Fatalf("canonical was removed: %v", err)
+	}
+	if _, err := os.Stat(ancestorPath); !os.IsNotExist(err) {
+		t.Fatalf("ancestor remained live: %v", err)
+	}
+}
+
+func TestSetRecoveryPreferredKeepsExactlyOneChoice(t *testing.T) {
+	dir := t.TempDir()
+	paths := []string{filepath.Join(dir, "left.jsonl"), filepath.Join(dir, "right.jsonl")}
+	for _, path := range paths {
+		session := NewSession("sys")
+		session.Add(provider.Message{Role: provider.RoleUser, Content: path})
+		if err := session.Save(path); err != nil {
+			t.Fatal(err)
+		}
+		if err := SaveBranchMeta(path, BranchMeta{ID: BranchID(path), Recovered: true, ParentID: "root"}); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err := SetRecoveryPreferred(paths, paths[0]); err != nil {
+		t.Fatal(err)
+	}
+	if err := SetRecoveryPreferred(paths, paths[1]); err != nil {
+		t.Fatal(err)
+	}
+	for index, path := range paths {
+		meta, ok, err := LoadBranchMeta(path)
+		if err != nil || !ok {
+			t.Fatalf("meta %q ok=%v err=%v", path, ok, err)
+		}
+		if meta.RecoveryPreferred != (index == 1) {
+			t.Fatalf("preferred[%d] = %v", index, meta.RecoveryPreferred)
+		}
+		if index == 1 && !RecoveryPreferenceCurrent(path, meta) {
+			t.Fatal("saved preference fingerprint was not current")
+		}
+	}
+	chosen, err := LoadSession(paths[1])
+	if err != nil {
+		t.Fatal(err)
+	}
+	chosen.Add(provider.Message{Role: provider.RoleAssistant, Content: "changed"})
+	if err := chosen.SaveSnapshot(paths[1]); err != nil {
+		t.Fatal(err)
+	}
+	meta, _, _ := LoadBranchMeta(paths[1])
+	if RecoveryPreferenceCurrent(paths[1], meta) {
+		t.Fatal("content change must invalidate the explicit preference")
+	}
+}
+
 func TestTrashReclaimableRecoveryBranchEnforcesGraceAtFinalGuard(t *testing.T) {
 	dir := t.TempDir()
 	parentPath, branchPath, branchMsgs := forkRecoveryBranch(t, dir, "trash-fresh")

internal/agent/save.go

@@ -58,6 +58,11 @@ var (
 	sessionFileLockPollInterval = 25 * time.Millisecond
 	sessionMetaLockWait         = 5 * time.Second
 	ErrSessionSnapshotConflict  = errors.New("session snapshot conflicts with newer transcript")
+	// ErrSessionExternallyRemoved means a live Session still has a verified
+	// baseline for path, but every authoritative transcript artifact disappeared.
+	// Treating it as a first save would silently recreate a file the user or an
+	// external cleanup tool deliberately removed.
+	ErrSessionExternallyRemoved = errors.New("session was removed while still open")
 	ErrSessionRecoveryNotNeeded = errors.New("session recovery not needed")
 	// ErrSessionFileLockHeld reports that another process kept the
 	// compatibility save lock for the full bounded acquisition window. Callers
@@ -516,9 +521,13 @@ func writeSessionMessages(path string, msgs []provider.Message) error {
 // checkSnapshotWrite decides whether this session may write msgs over path, and
 // whether the safe write shape is a no-op, append-only suffix, or full rewrite.
 func (s *Session) checkSnapshotWrite(path string, next []provider.Message, nextDigest [sha256.Size]byte, nextVersion uint64, allowOwnedRewrite bool) (snapshotWriteDecision, error) {
+	baseState := s.persistState(path)
 	current, err := loadSessionUnlocked(path)
 	if err != nil {
 		if os.IsNotExist(err) {
+			if baseState.ok {
+				return snapshotWriteDecision{}, ErrSessionExternallyRemoved
+			}
 			return snapshotWriteDecision{}, nil
 		}
 		return snapshotWriteDecision{}, err
@@ -527,7 +536,6 @@ func (s *Session) checkSnapshotWrite(path string, next []provider.Message, nextD
 	if err != nil {
 		return snapshotWriteDecision{}, err
 	}
-	baseState := s.persistState(path)
 	existing := current.Snapshot()
 	existingDigest, err := digestSessionMessages(existing)
 	if err != nil {
@@ -1538,19 +1546,20 @@ type SessionInfo struct {
 // session pickers and prompt-history navigation. It intentionally avoids reading
 // JSONL content; callers that need previews can layer that on afterwards.
 type SessionOrderInfo struct {
-	Path           string
-	CreatedAt      time.Time
-	LastActivityAt time.Time
-	ModTime        time.Time // compatibility alias for LastActivityAt
-	Scope          string
-	WorkspaceRoot  string
-	TopicID        string
-	TopicTitle     string
-	CustomTitle    string
-	Recovered      bool
-	RecoveryReason string
-	RecoveryDigest string
-	ParentID       string
+	Path              string
+	CreatedAt         time.Time
+	LastActivityAt    time.Time
+	ModTime           time.Time // compatibility alias for LastActivityAt
+	Scope             string
+	WorkspaceRoot     string
+	TopicID           string
+	TopicTitle        string
+	CustomTitle       string
+	Recovered         bool
+	RecoveryReason    string
+	RecoveryDigest    string
+	ParentID          string
+	RecoveryPreferred bool
 	// Turns and Preview are the cached listing fields from the sidecar; SchemaVersion
 	// >= agent.BranchMetaCountsVersion means they were recorded from content and can
 	// be trusted (even Turns == 0). ListSessions uses them to skip the whole-file decode.
@@ -2085,6 +2094,7 @@ func ListSessionOrder(dir string) ([]SessionOrderInfo, error) {
 		recoveryReason := ""
 		recoveryDigest := ""
 		parentID := ""
+		recoveryPreferred := false
 		turns := 0
 		preview := ""
 		schemaVersion := 0
@@ -2106,31 +2116,43 @@ func ListSessionOrder(dir string) ([]SessionOrderInfo, error) {
 			recoveryReason = meta.RecoveryReason
 			recoveryDigest = meta.RecoveryDigest
 			parentID = meta.ParentID
+			recoveryPreferred = RecoveryPreferenceCurrent(full, meta)
 			turns = meta.Turns
 			preview = meta.Preview
 			schemaVersion = meta.SchemaVersion
 			revision = meta.Revision
 			contentDigest = meta.ContentDigest
 		}
+		// Old recovery files may lack Recovered meta; filename still proves
+		// automatic recovery lineage for catalog folding.
+		if !recovered && LooksLikeRecoveryFilename(full) {
+			recovered = true
+			if parentID == "" {
+				if parent, ok := RecoveryFilenameParentID(full); ok {
+					parentID = parent
+				}
+			}
+		}
 		out = append(out, SessionOrderInfo{
-			Path:           full,
-			CreatedAt:      createdAt,
-			LastActivityAt: lastActivityAt,
-			ModTime:        lastActivityAt,
-			Scope:          scope,
-			WorkspaceRoot:  workspaceRoot,
-			TopicID:        topicID,
-			TopicTitle:     topicTitle,
-			CustomTitle:    customTitle,
-			Recovered:      recovered,
-			RecoveryReason: recoveryReason,
-			RecoveryDigest: recoveryDigest,
-			ParentID:       parentID,
-			Turns:          turns,
-			Preview:        preview,
-			SchemaVersion:  schemaVersion,
-			Revision:       revision,
-			ContentDigest:  contentDigest,
+			Path:              full,
+			CreatedAt:         createdAt,
+			LastActivityAt:    lastActivityAt,
+			ModTime:           lastActivityAt,
+			Scope:             scope,
+			WorkspaceRoot:     workspaceRoot,
+			TopicID:           topicID,
+			TopicTitle:        topicTitle,
+			CustomTitle:       customTitle,
+			Recovered:         recovered,
+			RecoveryReason:    recoveryReason,
+			RecoveryDigest:    recoveryDigest,
+			ParentID:          parentID,
+			RecoveryPreferred: recoveryPreferred,
+			Turns:             turns,
+			Preview:           preview,
+			SchemaVersion:     schemaVersion,
+			Revision:          revision,
+			ContentDigest:     contentDigest,
 		})
 	}
 	sort.Slice(out, func(i, j int) bool {

internal/agent/save_test.go

@@ -1895,6 +1895,28 @@ func TestSaveRecoveryBranchPersistsDivergedSnapshot(t *testing.T) {
 	}
 }
 
+func TestSaveSnapshotRefusesToRecreateExternallyRemovedBaseline(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "removed.jsonl")
+	s := NewSession("sys")
+	s.Add(provider.Message{Role: provider.RoleUser, Content: "keep me"})
+	if err := s.SaveSnapshot(path); err != nil {
+		t.Fatal(err)
+	}
+	for _, artifact := range append([]string{path}, store.SessionSidecarFiles(path)...) {
+		if err := os.RemoveAll(artifact); err != nil {
+			t.Fatal(err)
+		}
+	}
+	s.Add(provider.Message{Role: provider.RoleAssistant, Content: "still in memory"})
+	if err := s.SaveSnapshot(path); !errors.Is(err, ErrSessionExternallyRemoved) {
+		t.Fatalf("SaveSnapshot error = %v, want ErrSessionExternallyRemoved", err)
+	}
+	if _, err := os.Stat(path); !os.IsNotExist(err) {
+		t.Fatalf("removed path was silently recreated: %v", err)
+	}
+}
+
 func TestSaveRecoveryBranchSkipsPureStalePrefix(t *testing.T) {
 	path := filepath.Join(t.TempDir(), "session.jsonl")
 	current := NewSession("sys")

internal/agent/shell_contract_test.go

@@ -178,6 +178,61 @@ func TestBatchDependencyBarrierSkipsVerificationAfterFailedMutation(t *testing.T
 	t.Fatal("verify tool result missing")
 }
 
+func TestBatchDependencyBarrierReportsSanitizedRepositoryCause(t *testing.T) {
+	var calls int32
+	reg := tool.NewRegistry()
+	reg.Add(fakeTool{name: "bash", readOnly: false, err: fmt.Errorf("synthetic failure"), calls: &calls})
+	prov := &scriptedProvider{name: "p", turns: [][]provider.Chunk{
+		{
+			toolCallChunk("w1", "bash", `{"command":"git tag private-release-name"}`),
+			toolCallChunk("v1", "bash", `{"command":"go test ./..."}`),
+			{Type: provider.ChunkDone},
+		},
+		{{Type: provider.ChunkText, Text: "done"}, {Type: provider.ChunkDone}},
+	}}
+	a := New(prov, reg, NewSession(""), Options{}, event.Discard)
+	if err := a.Run(context.Background(), "tag then verify"); err != nil {
+		t.Fatal(err)
+	}
+	got := toolResultByID(a.sess.conversation, "v1")
+	if !strings.Contains(got, "repository metadata") {
+		t.Fatalf("dependency result = %q, want repository metadata cause", got)
+	}
+	if strings.Contains(got, "private-release-name") {
+		t.Fatalf("dependency result leaked command operand: %q", got)
+	}
+	if calls != 1 {
+		t.Fatalf("bash Execute calls = %d, want only the failed writer", calls)
+	}
+}
+
+func TestBatchDependencyBarrierDoesNotOpenForFailedBranchListing(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "x.txt"), []byte("a\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	reg := tool.NewRegistry()
+	reg.Add(fakeTool{name: "bash", readOnly: false, err: fmt.Errorf("synthetic reader failure")})
+	for _, tl := range (builtin.Workspace{Dir: dir}).Tools("edit_file") {
+		reg.Add(tl)
+	}
+	a := New(nil, reg, NewSession(""), Options{}, event.Discard)
+	batch := a.executeBatch(context.Background(), &a.turn, []provider.ToolCall{
+		{ID: "r1", Name: "bash", Arguments: `{"command":"git branch -a"}`},
+		{ID: "e1", Name: "edit_file", Arguments: `{"path":"x.txt","old_string":"a","new_string":"b"}`},
+	})
+	if got := batch.results[1]; strings.Contains(got, "earlier") || strings.HasPrefix(strings.TrimSpace(got), "blocked:") {
+		t.Fatalf("edit was dependency-blocked after reader failure: %q", got)
+	}
+	got, err := os.ReadFile(filepath.Join(dir, "x.txt"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(got) != "b\n" {
+		t.Fatalf("file = %q, want edit to run after failed reader", string(got))
+	}
+}
+
 // TestBatchDependencyBarrierIgnoresFailedNonMutationMetaTool keeps bookkeeping
 // writers out of the barrier. todo_write, complete_step, ask, bash_output and
 // wait all report ReadOnly()==false, but evidence.ToolCallMutates deliberately

internal/agent/taskpolicy_execution_test.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"encoding/json"
 	"strings"
+	"sync/atomic"
 	"testing"
 
 	"reasonix/internal/event"
@@ -13,6 +14,53 @@ import (
 	"reasonix/internal/tool"
 )
 
+func TestTaskPolicyUsesStructuredCommandEffects(t *testing.T) {
+	var calls int32
+	reg := tool.NewRegistry()
+	reg.Add(fakeTool{name: "bash", readOnly: false, calls: &calls})
+	a := New(&scriptedProvider{name: "p"}, reg, NewSession("sys"), Options{}, event.Discard)
+	a.turn.policy = taskpolicy.TaskPolicy{Constraints: taskpolicy.Constraints{ForbidMutation: true}}
+	a.turn.policySet = true
+
+	listing := a.executeOne(context.Background(), &a.turn, provider.ToolCall{Name: "bash", Arguments: `{"command":"git branch -a"}`})
+	if listing.blocked || listing.errMsg != "" {
+		t.Fatalf("branch listing outcome = %+v, want execution", listing)
+	}
+	if got := atomic.LoadInt32(&calls); got != 1 {
+		t.Fatalf("branch listing Execute calls = %d, want 1", got)
+	}
+
+	tests := []struct {
+		name       string
+		command    string
+		wantDomain string
+		secret     string
+	}{
+		{name: "tag creation", command: "git tag v1.2.3", wantDomain: "repository metadata", secret: "v1.2.3"},
+		{name: "host clock", command: "date --set tomorrow", wantDomain: "host state", secret: "tomorrow"},
+		{name: "audit fix", command: "npm audit fix", wantDomain: "workspace content", secret: "fix"},
+		{name: "config edit", command: "git config --edit", wantDomain: "repository metadata", secret: "--edit"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			args, err := json.Marshal(map[string]string{"command": tt.command})
+			if err != nil {
+				t.Fatal(err)
+			}
+			got := a.executeOne(context.Background(), &a.turn, provider.ToolCall{Name: "bash", Arguments: string(args)})
+			if !got.blocked || !strings.Contains(got.errMsg, tt.wantDomain) {
+				t.Fatalf("command %q outcome = %+v, want %q mutation block", tt.command, got, tt.wantDomain)
+			}
+			if strings.Contains(got.errMsg, tt.secret) && tt.secret != "--edit" {
+				t.Fatalf("policy error leaked command operand %q: %q", tt.secret, got.errMsg)
+			}
+		})
+	}
+	if got := atomic.LoadInt32(&calls); got != 1 {
+		t.Fatalf("blocked writers reached Execute: calls=%d, want 1", got)
+	}
+}
+
 func TestTaskPolicyEnforcesVerificationAllowlist(t *testing.T) {
 	reg := tool.NewRegistry()
 	reg.Add(fakeTool{name: "bash", readOnly: true})

internal/agent/taskpolicy_gate.go

@@ -11,8 +11,15 @@ func (a *Agent) taskPolicyToolGate(plan *toolCallPlan, args json.RawMessage) (to
 	if !a.turn.policySet {
 		return toolOutcome{}, false
 	}
-	if plan.mutates && !a.turn.policy.AllowsMutation() {
-		return policyBlock("the current task policy forbids workspace modifications (user constraint or plan mode)", "task policy forbids mutation")
+	if plan.effects.StateMutation && !a.turn.policy.AllowsMutation() {
+		reason := strings.TrimSpace(plan.effects.Reason)
+		if reason == "" {
+			reason = "state mutation whose effects cannot be proven read-only"
+		}
+		return policyBlock(
+			"the current task policy forbids "+reason+" (user constraint or plan mode)",
+			"task policy forbids "+reason,
+		)
 	}
 	if !a.turn.policy.AllowsExternal() && isExternalActionTool(plan.evidenceName, plan.permName, args) {
 		return policyBlock("the current task policy forbids push/publish/deploy-style external actions", "task policy forbids external action")

internal/agent/tool_call_plan.go

@@ -0,0 +1,41 @@
+package agent
+
+import (
+	"context"
+	"encoding/json"
+
+	"reasonix/internal/evidence"
+	"reasonix/internal/provider"
+	"reasonix/internal/tool"
+)
+
+// toolCallPlan is the resolved, policy-checked state owned by one executeOne.
+type toolCallPlan struct {
+	call                                          provider.ToolCall
+	tool                                          tool.Tool
+	canonicalName                                 string
+	permName                                      string
+	permArgs                                      json.RawMessage
+	execTool                                      tool.Tool
+	execArgs                                      json.RawMessage
+	evidenceName                                  string
+	evidenceArgs                                  json.RawMessage
+	readOnly                                      bool
+	resolved                                      tool.ResolvedCall
+	resolvedMeta                                  *tool.ResolvedCall
+	effects                                       evidence.ToolEffects
+	verification, planTransition                  bool
+	planBefore, planAfter, planDiff               string
+	planReplacementAuthorized                     bool
+	recoveryGen                                   uint64
+	runTool                                       tool.Tool
+	runArgs                                       json.RawMessage
+	cctx                                          context.Context
+	releaseParentWrite, releaseMutationWrite      func()
+	mutationPath                                  string
+	mutationObserved, mutationAfterDone, executed bool
+}
+
+func (p *toolCallPlan) classifyEffects() {
+	p.effects = evidence.ClassifyToolCall(p.evidenceName, p.evidenceArgs, p.readOnly)
+}

internal/agent/tool_receipts.go

@@ -10,6 +10,12 @@ import (
 // recordToolReceipts files the turn-scoped evidence for one executed call:
 // always the model-visible call for audit, plus the real target's attributes
 // for mutation/read classification when a proxy resolved elsewhere.
+func (a *Agent) finalizeObservedToolReceipts(plan *toolCallPlan, result string, execution *tool.ShellExecution, err error) {
+	a.observeAfterMutation(plan)
+	plan.mutationAfterDone = true
+	a.recordToolReceipts(plan, result, execution, err)
+}
+
 func (a *Agent) recordToolReceipts(plan *toolCallPlan, result string, execution *tool.ShellExecution, err error) {
 	if a.task.ledger == nil {
 		return
@@ -26,10 +32,12 @@ func (a *Agent) recordToolReceipts(plan *toolCallPlan, result string, execution
 	case plan.evidenceName != call.Name:
 		a.task.ledger.Record(evidence.ReceiptFromToolCall(call.Name, args, err == nil, true))
 		rec := evidence.ReceiptFromToolCall(plan.evidenceName, plan.evidenceArgs, err == nil, plan.readOnly)
+		rec.Mutation = plan.effects.ContentMutation
 		decorateExecutionReceipt(&rec, result, execution)
 		a.task.ledger.Record(rec)
 	default:
 		rec := evidence.ReceiptFromToolCall(call.Name, args, err == nil, plan.tool.ReadOnly())
+		rec.Mutation = plan.effects.ContentMutation
 		decorateExecutionReceipt(&rec, result, execution)
 		a.task.ledger.Record(rec)
 		if err == nil && call.Name == "todo_write" {

internal/agent/workspace_mutation.go

@@ -2,13 +2,11 @@ package agent
 
 import (
 	"encoding/json"
-	"path/filepath"
 	"strings"
 	"sync"
 
 	"reasonix/internal/event"
 	"reasonix/internal/evidence"
-	"reasonix/internal/shellparse"
 )
 
 type workspaceEffectiveCall struct {
@@ -53,7 +51,11 @@ func recordWorkspaceMutation(sink event.Sink, mutation *event.WorkspaceMutation)
 // git commit, which changes HEAD/index/history without changing file contents.
 func workspaceMutationForCall(toolID, toolName string, args json.RawMessage, readOnly bool) (event.WorkspaceMutation, bool) {
 	toolName = strings.TrimSpace(toolName)
-	if toolName == "" || readOnly || evidence.IsNonMutationMetaTool(toolName) || workspaceHostStateOnlyTool(toolName) {
+	if toolName == "" || evidence.IsNonMutationMetaTool(toolName) || workspaceHostStateOnlyTool(toolName) {
+		return event.WorkspaceMutation{}, false
+	}
+	effects := evidence.ClassifyToolCall(toolName, args, readOnly)
+	if !effects.WorkspaceMutation {
 		return event.WorkspaceMutation{}, false
 	}
 
@@ -63,12 +65,10 @@ func workspaceMutationForCall(toolID, toolName string, args json.RawMessage, rea
 		ToolName:    toolName,
 		Paths:       paths,
 		AllPaths:    toolName == "bash" || len(paths) == 0,
-		Content:     true,
-		Tree:        true,
-		WorkingTree: true,
-	}
-	if toolName == "bash" {
-		mutation.GitMeta = bashMayChangeGitMetadata(bashCommandFromArgs(args))
+		Content:     effects.ContentMutation,
+		Tree:        effects.ContentMutation,
+		WorkingTree: effects.ContentMutation,
+		GitMeta:     effects.RepositoryMutation,
 	}
 	return mutation, true
 }
@@ -84,54 +84,3 @@ func workspaceHostStateOnlyTool(toolName string) bool {
 		return false
 	}
 }
-
-func bashMayChangeGitMetadata(command string) bool {
-	segments, _, ok := shellparse.SplitTopLevel(command)
-	if !ok {
-		return commandMentionsGitExecutable(command)
-	}
-	for _, segment := range segments {
-		fields, malformed := shellparse.StaticFields(strings.TrimSpace(segment))
-		if malformed != "" {
-			if commandMentionsGitExecutable(segment) {
-				return true
-			}
-			continue
-		}
-		fields = stripWorkspaceEnvPrefix(fields)
-		if len(fields) == 0 || !isGitExecutable(fields[0]) {
-			continue
-		}
-		// A non-read-only bash call that reaches an explicit git executable is
-		// conservatively Git metadata changing. Host read-only classification
-		// has already removed status/diff/log-style calls before this point.
-		return true
-	}
-	return false
-}
-
-func stripWorkspaceEnvPrefix(fields []string) []string {
-	for len(fields) > 0 {
-		if fields[0] == "env" || (strings.Contains(fields[0], "=") && !strings.HasPrefix(fields[0], "-")) {
-			fields = fields[1:]
-			continue
-		}
-		break
-	}
-	return fields
-}
-
-func commandMentionsGitExecutable(command string) bool {
-	for field := range strings.FieldsSeq(command) {
-		field = strings.Trim(field, "'\"(){}[];|&")
-		if isGitExecutable(field) {
-			return true
-		}
-	}
-	return false
-}
-
-func isGitExecutable(field string) bool {
-	base := strings.ToLower(filepath.Base(strings.TrimSpace(field)))
-	return base == "git" || base == "git.exe"
-}

internal/agent/workspace_mutation_test.go

@@ -4,11 +4,14 @@ import (
 	"context"
 	"encoding/json"
 	"errors"
+	"os"
 	"strings"
 	"testing"
 	"time"
 
+	"reasonix/internal/checkpoint"
 	"reasonix/internal/event"
+	"reasonix/internal/evidence"
 	"reasonix/internal/extension"
 	"reasonix/internal/extension/dispatch"
 	"reasonix/internal/extension/protocol"
@@ -16,6 +19,45 @@ import (
 	"reasonix/internal/tool"
 )
 
+func TestObservedFileChangePromotesRepositoryOnlyReceiptToContentMutation(t *testing.T) {
+	root := t.TempDir()
+	path := root + "/tracked.txt"
+	if err := os.WriteFile(path, []byte("before"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	store := checkpoint.New("", root)
+	store.Begin(1, "commit", 0)
+	observer := checkpoint.NewMutationObserver(checkpoint.ObserverOptions{Store: store})
+	observer.BeforeMutation(path, "bash", checkpoint.CaptureBeforeMutation)
+
+	reg := tool.NewRegistry()
+	bash := fakeTool{name: "bash", readOnly: false}
+	reg.Add(bash)
+	a := New(nil, reg, NewSession(""), Options{MutationObserver: observer}, event.Discard)
+	args := json.RawMessage(`{"command":"git commit -m checkpoint"}`)
+	plan := &toolCallPlan{
+		call:         provider.ToolCall{ID: "commit", Name: "bash", Arguments: string(args)},
+		tool:         bash,
+		evidenceName: "bash",
+		evidenceArgs: args,
+		effects:      evidence.ClassifyToolCall("bash", args, false),
+		mutationPath: path,
+	}
+	if plan.effects.ContentMutation {
+		t.Fatal("pure commit should begin as repository-only")
+	}
+	if err := os.WriteFile(path, []byte("changed by hook"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if !a.observeAfterMutation(plan) || !plan.effects.ContentMutation {
+		t.Fatalf("observed effect was not promoted: %+v", plan.effects)
+	}
+	a.recordToolReceipts(plan, "", nil, nil)
+	if _, ok := a.task.ledger.LatestSuccessfulMutationIndex(); !ok {
+		t.Fatal("promoted receipt was not recorded as a content mutation")
+	}
+}
+
 func TestToolBeforeWorkspaceMutationUsesExecutedReplacement(t *testing.T) {
 	t.Run("reader replaced by writer", func(t *testing.T) {
 		client := &fakeDispatchClient{interceptFn: func(ev protocol.InterceptEvent, _ json.RawMessage) (protocol.InterceptResult, error) {

internal/checkpoint/capture_after.go

@@ -0,0 +1,53 @@
+package checkpoint
+
+import "slices"
+
+// CaptureAfter records the after fingerprint and reports a preimage change.
+func (s *Store) CaptureAfter(path string, opts CaptureAfterOpts) bool {
+	if path == "" {
+		return false
+	}
+	pathKey := NormalizeRelPath(s.root, path)
+	fp, gap, err := CapturePath(path, CaptureOptions{WorkspaceRoot: s.root, ReadContent: true})
+	if gap != nil {
+		s.RecordGap(*gap)
+	}
+	if err != nil {
+		return false
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.mutationSeq = opts.Seq
+	if s.cur != nil {
+		s.cur.LastMutationSeq = opts.Seq
+		for i := range s.cur.Files {
+			if NormalizeRelPath(s.root, s.cur.Files[i].Path) != pathKey {
+				continue
+			}
+			changed := updateAfterFingerprint(&s.cur.Files[i], fp)
+			s.recomputeCoverageLocked(s.cur)
+			s.persistBestEffort(s.cur)
+			s.lastUndo = nil
+			return changed
+		}
+	}
+	for _, c := range slices.Backward(s.done) {
+		for j := range c.Files {
+			if NormalizeRelPath(s.root, c.Files[j].Path) != pathKey {
+				continue
+			}
+			changed := updateAfterFingerprint(&c.Files[j], fp)
+			s.persistBestEffort(c)
+			s.lastUndo = nil
+			return changed
+		}
+	}
+	return false
+}
+
+func updateAfterFingerprint(before *FileSnap, after Fingerprint) bool {
+	existed := before.Content != nil || before.BlobRef != "" || before.SHA256 != ""
+	changed := existed != after.Existed || before.SHA256 != after.SHA256 || before.Mode != after.Mode
+	before.AfterExisted, before.AfterSHA256, before.AfterMode = &after.Existed, after.SHA256, after.Mode
+	return changed
+}

internal/checkpoint/checkpoint.go

@@ -20,7 +20,6 @@ import (
 	"log/slog"
 	"os"
 	"path/filepath"
-	"slices"
 	"sort"
 	"strings"
 	"sync"
@@ -499,68 +498,6 @@ func (s *Store) CaptureBefore(path string, opts CaptureBeforeOpts) {
 	s.persistBestEffort(s.cur)
 }
 
-// CaptureAfter records the after fingerprint for a path already in the current
-// (or any) checkpoint that owns it.
-func (s *Store) CaptureAfter(path string, opts CaptureAfterOpts) {
-	if path == "" {
-		return
-	}
-	pathKey := NormalizeRelPath(s.root, path)
-	fp, gap, err := CapturePath(path, CaptureOptions{
-		WorkspaceRoot: s.root,
-		ReadContent:   true,
-	})
-	if gap != nil {
-		s.RecordGap(*gap)
-	}
-	_ = err
-
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	s.mutationSeq = opts.Seq
-	if s.cur != nil {
-		s.cur.LastMutationSeq = opts.Seq
-	}
-	// Update after fingerprint on the most recent snap of this path.
-	updated := false
-	if s.cur != nil {
-		for i := range s.cur.Files {
-			if NormalizeRelPath(s.root, s.cur.Files[i].Path) != pathKey {
-				continue
-			}
-			existed := fp.Existed
-			s.cur.Files[i].AfterExisted = &existed
-			s.cur.Files[i].AfterSHA256 = fp.SHA256
-			s.cur.Files[i].AfterMode = fp.Mode
-			updated = true
-		}
-		if updated {
-			s.recomputeCoverageLocked(s.cur)
-			s.persistBestEffort(s.cur)
-			s.lastUndo = nil // mutation invalidates undo
-			return
-		}
-	}
-	// Path might only appear in earlier turns; still record after on earliest?
-	// Ownership after is per-path last write — update the latest checkpoint that
-	// has this path.
-	for _, v := range slices.Backward(s.done) {
-		c := v
-		for j := range c.Files {
-			if NormalizeRelPath(s.root, c.Files[j].Path) != pathKey {
-				continue
-			}
-			existed := fp.Existed
-			c.Files[j].AfterExisted = &existed
-			c.Files[j].AfterSHA256 = fp.SHA256
-			c.Files[j].AfterMode = fp.Mode
-			s.persistBestEffort(c)
-			s.lastUndo = nil
-			return
-		}
-	}
-}
-
 // RecordGap appends a coverage gap to the current checkpoint.
 func (s *Store) RecordGap(gap CoverageGap) {
 	if s == nil {

internal/checkpoint/observer.go

@@ -224,14 +224,15 @@ func (o *MutationObserver) BeforeMutationFromChange(ch diff.Change, tool string)
 	})
 }
 
-// AfterMutation re-reads the path after a tool attempt (success or failure) and
-// records the after fingerprint under Reasonix ownership.
-func (o *MutationObserver) AfterMutation(path, tool string) {
+// AfterMutation re-reads the path after a tool attempt (success or failure),
+// records the after fingerprint under Reasonix ownership, and reports whether
+// the captured workspace content actually changed.
+func (o *MutationObserver) AfterMutation(path, tool string) bool {
 	if o == nil || o.store == nil || path == "" {
-		return
+		return false
 	}
 	seq := o.seq.Add(1)
-	o.store.CaptureAfter(path, CaptureAfterOpts{
+	return o.store.CaptureAfter(path, CaptureAfterOpts{
 		Seq:           seq,
 		Tool:          tool,
 		Source:        CaptureAfterMutation,

internal/cli/doctor.go

@@ -117,7 +117,11 @@ func doctorSessionsCommand(args []string) int {
 	fmt.Printf("  mode: %s\n", status.Mode)
 	fmt.Printf("  revision: %d\n", status.Revision)
 	fmt.Printf("  indexed: %d\n", status.Indexed)
+	fmt.Printf("  physical sessions: %d\n", status.PhysicalSessions)
+	fmt.Printf("  logical sessions: %d\n", status.LogicalSessions)
 	fmt.Printf("  repair pending: %d\n", status.RepairPending)
+	fmt.Printf("  recovery: %d groups, %d branches, %d diverged, %d safe cleanup\n",
+		status.RecoveryGroups, status.RecoveryBranches, status.RecoveryDiverged, status.CleanupEligible)
 	if status.LastError != "" {
 		fmt.Printf("  note: %s\n", status.LastError)
 	}

internal/cli/sessions_catalog.go

@@ -3,12 +3,14 @@ package cli
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"flag"
 	"fmt"
 	"os"
 	"path/filepath"
 	"strings"
 
+	"reasonix/internal/agent"
 	"reasonix/internal/config"
 	"reasonix/internal/sessioncatalog"
 )
@@ -21,8 +23,18 @@ func sessionOrSessionsCommand(command string, args []string) int {
 }
 
 func sessionsCommand(args []string) int {
-	if len(args) == 0 || args[0] != "reindex" {
-		fmt.Fprintln(os.Stderr, "usage: reasonix sessions reindex [--dir PATH] [--json]")
+	if len(args) == 0 {
+		fmt.Fprintln(os.Stderr, "usage: reasonix sessions <reindex|diagnose|cleanup> [--dir PATH] [--json]")
+		return 2
+	}
+	switch args[0] {
+	case "diagnose":
+		return sessionsRecoveryCommand(args[1:], false)
+	case "cleanup":
+		return sessionsRecoveryCommand(args[1:], true)
+	case "reindex":
+	default:
+		fmt.Fprintln(os.Stderr, "usage: reasonix sessions <reindex|diagnose|cleanup> [--dir PATH] [--json]")
 		return 2
 	}
 	fs := flag.NewFlagSet("sessions reindex", flag.ContinueOnError)
@@ -62,6 +74,144 @@ func sessionsCommand(args []string) int {
 	return printSessionCatalogRebuild(status, *jsonOut)
 }
 
+type sessionRecoveryReport struct {
+	Directories     int      `json:"directories"`
+	Groups          int      `json:"groups"`
+	Branches        int      `json:"branches"`
+	AdoptedGroups   int      `json:"adoptedGroups"`
+	DivergedGroups  int      `json:"divergedGroups"`
+	CleanupEligible int      `json:"cleanupEligible"`
+	MovedToTrash    int      `json:"movedToTrash"`
+	Busy            int      `json:"busy"`
+	Errors          []string `json:"errors"`
+	DryRun          bool     `json:"dryRun"`
+}
+
+func sessionsRecoveryCommand(args []string, cleanup bool) int {
+	name := "sessions diagnose"
+	if cleanup {
+		name = "sessions cleanup"
+	}
+	fs := flag.NewFlagSet(name, flag.ContinueOnError)
+	var dirs stringListFlag
+	apply := fs.Bool("apply", false, "move safe covered recovery branches to recoverable trash")
+	jsonOut := fs.Bool("json", false, "print the recovery report as JSON")
+	fs.Var(&dirs, "dir", "session directory to inspect; repeat for multiple directories")
+	if code, ok := parseCommandFlags(fs, args); !ok {
+		return code
+	}
+	if fs.NArg() != 0 || (!cleanup && *apply) {
+		fmt.Fprintf(os.Stderr, "usage: reasonix %s [--dir PATH] [--json]", name)
+		if cleanup {
+			fmt.Fprint(os.Stderr, " [--apply]")
+		}
+		fmt.Fprintln(os.Stderr)
+		return 2
+	}
+	if len(dirs) == 0 {
+		for _, target := range defaultSessionCatalogTargets() {
+			dirs = append(dirs, target.Path)
+		}
+	}
+	report := sessionRecoveryReport{Errors: []string{}, DryRun: !cleanup || !*apply}
+	seen := map[string]bool{}
+	for _, rawDir := range dirs {
+		dir := filepath.Clean(strings.TrimSpace(rawDir))
+		if dir == "." || dir == "" || seen[dir] {
+			continue
+		}
+		seen[dir] = true
+		report.Directories++
+		catalog, err := sessioncatalog.Open(context.Background(), sessioncatalog.Options{InMemory: true, DisableRepair: true})
+		if err != nil {
+			report.Errors = append(report.Errors, err.Error())
+			continue
+		}
+		err = catalog.ReconcileDirectory(context.Background(), sessioncatalog.DirectoryTarget{Path: dir, Scope: "global"})
+		if err != nil {
+			report.Errors = append(report.Errors, err.Error())
+			_ = catalog.Close(context.Background())
+			continue
+		}
+		groups, err := catalog.ListRecoveryGroups(context.Background(), dir)
+		if err != nil {
+			report.Errors = append(report.Errors, err.Error())
+			_ = catalog.Close(context.Background())
+			continue
+		}
+		for _, group := range groups {
+			rootID, members := group.ID, group.Members
+			report.Groups++
+			report.Branches += len(members)
+			canonical := ""
+			diverged := false
+			for _, member := range members {
+				if member.RecoveryCanonical && (member.RecoveryRole == sessioncatalog.RecoveryRoleAdopted || member.RecoveryRole == sessioncatalog.RecoveryRolePreferred) {
+					canonical = member.Path
+				}
+				if member.RecoveryRole == sessioncatalog.RecoveryRoleDiverged {
+					diverged = true
+				}
+			}
+			if canonical == "" {
+				if diverged {
+					report.DivergedGroups++
+				}
+				continue
+			}
+			report.AdoptedGroups++
+			candidates := []string{}
+			for _, member := range members {
+				if member.Path != canonical && member.RecoveryRole == sessioncatalog.RecoveryRoleCoveredCopy {
+					candidates = append(candidates, member.Path)
+				}
+			}
+			report.CleanupEligible += len(candidates)
+			if report.DryRun || len(candidates) == 0 {
+				continue
+			}
+			if err := agent.ReparentRecoveryCanonical(canonical, rootID, dir); err != nil {
+				if errors.Is(err, agent.ErrSessionLeaseHeld) {
+					report.Busy += len(candidates)
+				} else {
+					report.Errors = append(report.Errors, err.Error())
+				}
+				continue
+			}
+			for _, candidate := range candidates {
+				if err := agent.TrashRecoveryBranchCoveredBy(candidate, canonical, dir); err != nil {
+					if errors.Is(err, agent.ErrSessionLeaseHeld) {
+						report.Busy++
+					} else {
+						report.Errors = append(report.Errors, err.Error())
+					}
+					continue
+				}
+				report.MovedToTrash++
+			}
+		}
+		_ = catalog.Close(context.Background())
+	}
+	if *jsonOut {
+		enc := json.NewEncoder(os.Stdout)
+		enc.SetIndent("", "  ")
+		_ = enc.Encode(report)
+	} else {
+		fmt.Printf("recovery groups: %d (%d adopted, %d diverged)\n", report.Groups, report.AdoptedGroups, report.DivergedGroups)
+		fmt.Printf("recovery branches: %d; safe cleanup: %d; moved: %d; busy: %d\n", report.Branches, report.CleanupEligible, report.MovedToTrash, report.Busy)
+		if report.DryRun && cleanup {
+			fmt.Println("dry run; pass --apply to move safe branches to recoverable trash")
+		}
+	}
+	for _, message := range report.Errors {
+		fmt.Fprintln(os.Stderr, "warning:", message)
+	}
+	if len(report.Errors) > 0 {
+		return 1
+	}
+	return 0
+}
+
 func printSessionCatalogRebuild(status sessioncatalog.Status, jsonOut bool) int {
 	if jsonOut {
 		enc := json.NewEncoder(os.Stdout)

internal/cli/shell_completion.go

@@ -215,6 +215,12 @@ func cliCompletionRootSpec() cliCompletionSpec {
 			completionSpec("reindex", []cliCompletionFlag{
 				completionFlag("--json", cliCompletionNoValue), completionFlag("--dir", cliCompletionPathValue), help,
 			}),
+			completionSpec("diagnose", []cliCompletionFlag{
+				completionFlag("--json", cliCompletionNoValue), completionFlag("--dir", cliCompletionPathValue), help,
+			}),
+			completionSpec("cleanup", []cliCompletionFlag{
+				completionFlag("--json --apply", cliCompletionNoValue), completionFlag("--dir", cliCompletionPathValue), help,
+			}),
 		),
 		catalogCompletionSpec(help),
 		completionSpec("report", []cliCompletionFlag{help},

internal/config/deepseek_protocol_migration_test.go

@@ -607,7 +607,7 @@ func TestCanUpgradeDeepSeekProviderProtocolRejectsProxyButAllowsExplicitUpgradeO
 	}
 }
 
-func TestNormalizeOfficialDeepSeekModelsDoesNotAddProToResponses(t *testing.T) {
+func TestNormalizeOfficialDeepSeekModelsAddsProToResponses(t *testing.T) {
 	c := &Config{Providers: []ProviderEntry{{
 		Name: "deepseek", Kind: "responses", BaseURL: "https://api.deepseek.com",
 		Model: "deepseek-v4-flash",
@@ -618,10 +618,96 @@ func TestNormalizeOfficialDeepSeekModelsDoesNotAddProToResponses(t *testing.T) {
 	if !ok {
 		t.Fatal("DeepSeek provider missing after normalization")
 	}
-	if !p.HasModel("deepseek-v4-flash") {
-		t.Fatal("Responses provider lost its Flash model")
+	if !p.HasModel("deepseek-v4-flash") || !p.HasModel("deepseek-v4-pro") {
+		t.Fatalf("Responses models = %v, want Flash and Pro", p.ModelList())
 	}
-	if p.HasModel("deepseek-v4-pro") {
-		t.Fatalf("Responses normalization added unsupported Pro model: %+v", p.ModelList())
+}
+
+func TestNormalizeOfficialDeepSeekResponsesPresetAddsPro(t *testing.T) {
+	c := &Config{Providers: []ProviderEntry{{
+		Name: "deepseek-responses", Kind: "responses", BaseURL: "https://api.deepseek.com",
+		Models: []string{"deepseek-v4-flash"}, Default: "deepseek-v4-flash",
+	}}}
+
+	normalizeOfficialDeepSeekModels(c)
+	p, ok := c.Provider("deepseek-responses")
+	if !ok {
+		t.Fatal("deepseek-responses provider missing after normalization")
+	}
+	if !p.HasModel("deepseek-v4-flash") || !p.HasModel("deepseek-v4-pro") {
+		t.Fatalf("deepseek-responses models = %v, want Flash and Pro", p.ModelList())
+	}
+	if p.Default != "deepseek-v4-flash" {
+		t.Fatalf("default = %q, want deepseek-v4-flash", p.Default)
+	}
+	flash := p.ModelOverrides["deepseek-v4-flash"]
+	if !containsString(flash.SupportedEfforts, "low") {
+		t.Fatalf("Flash effort override = %+v", flash)
+	}
+	pro := p.ModelOverrides["deepseek-v4-pro"]
+	if containsString(pro.SupportedEfforts, "low") || !containsString(pro.SupportedEfforts, "max") {
+		t.Fatalf("Pro effort override = %+v", pro)
+	}
+}
+
+func TestNormalizeOfficialDeepSeekResponsesDoesNotRestoreUncheckedPro(t *testing.T) {
+	cases := []struct {
+		name      string
+		overrides map[string]ProviderModelOverride
+	}{
+		{
+			name: "settings uncheck keeps flash override",
+			overrides: map[string]ProviderModelOverride{
+				"deepseek-v4-flash": {SupportedEfforts: []string{"disabled", "low", "high", "max"}, DefaultEffort: "high"},
+			},
+		},
+		{
+			name: "leftover pro override is still treated as curated",
+			overrides: map[string]ProviderModelOverride{
+				"deepseek-v4-pro": {SupportedEfforts: []string{"disabled", "high", "max"}, DefaultEffort: "high"},
+			},
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			c := &Config{Providers: []ProviderEntry{{
+				Name: "deepseek-responses", Kind: "responses", BaseURL: "https://api.deepseek.com",
+				Models: []string{"deepseek-v4-flash"}, Default: "deepseek-v4-flash",
+				ModelOverrides: tc.overrides,
+			}}}
+
+			normalizeOfficialDeepSeekModels(c)
+			p, ok := c.Provider("deepseek-responses")
+			if !ok {
+				t.Fatal("deepseek-responses provider missing after normalization")
+			}
+			if p.HasModel("deepseek-v4-pro") {
+				t.Fatalf("unchecked Pro was restored: %v", p.ModelList())
+			}
+		})
+	}
+}
+
+func TestNormalizeOfficialDeepSeekResponsesAddsProPriceForLegacyFlashPrice(t *testing.T) {
+	flash := deepSeekV4FlashPriceUSD()
+	c := &Config{Providers: []ProviderEntry{{
+		Name: "deepseek-responses", Kind: "responses", BaseURL: "https://api.deepseek.com",
+		Models: []string{"deepseek-v4-flash"}, Default: "deepseek-v4-flash",
+		Price: flash,
+	}}}
+
+	normalizeOfficialDeepSeekModels(c)
+	p, ok := c.Provider("deepseek-responses")
+	if !ok {
+		t.Fatal("deepseek-responses provider missing after normalization")
+	}
+	if !p.HasModel("deepseek-v4-pro") {
+		t.Fatalf("Responses models = %v, want Flash and Pro", p.ModelList())
+	}
+	if got := p.PriceForModel("deepseek-v4-flash"); !samePricing(got, flash) {
+		t.Fatalf("Flash price = %+v, want legacy singular price %+v", got, flash)
+	}
+	if got := p.PriceForModel("deepseek-v4-pro"); !samePricing(got, deepSeekV4ProPriceUSD()) {
+		t.Fatalf("Pro price = %+v, want official Pro list price", got)
 	}
 }

internal/config/deepseek_responses.go

@@ -0,0 +1,108 @@
+package config
+
+import (
+	"strings"
+
+	"reasonix/internal/provider"
+)
+
+func deepSeekV4EffortOverrides() map[string]ProviderModelOverride {
+	return map[string]ProviderModelOverride{
+		"deepseek-v4-flash": {SupportedEfforts: []string{"disabled", "low", "high", "max"}, DefaultEffort: "high"},
+		"deepseek-v4-pro":   {SupportedEfforts: []string{"disabled", "high", "max"}, DefaultEffort: "high"},
+	}
+}
+
+func isOfficialDeepSeekResponsesProvider(p *ProviderEntry) bool {
+	return p != nil && strings.EqualFold(strings.TrimSpace(p.Kind), "responses") &&
+		officialProviderHost(p.BaseURL) == "api.deepseek.com"
+}
+
+// backfillOfficialDeepSeekResponsesModels upgrades the previous canned
+// Flash-only official Responses contract. Settings drops overrides for
+// unchecked models, so any leftover ModelOverrides means the list is curated.
+func backfillOfficialDeepSeekResponsesModels(p *ProviderEntry) {
+	if !isOfficialDeepSeekResponsesProvider(p) {
+		return
+	}
+	switch strings.TrimSpace(p.Name) {
+	case "deepseek", "deepseek-responses":
+	default:
+		return
+	}
+	if p.HasModel("deepseek-v4-pro") {
+		backfillOfficialDeepSeekResponsesProPrice(p)
+		return
+	}
+	models := p.ModelList()
+	if len(models) != 1 || models[0] != "deepseek-v4-flash" {
+		return
+	}
+	if len(p.ModelOverrides) > 0 {
+		return
+	}
+	p.Models = mergeModelLists(models, []string{"deepseek-v4-flash", "deepseek-v4-pro"})
+	p.Default = firstKnownModel(p.Default, p.Models, "deepseek-v4-flash")
+	backfillOfficialDeepSeekResponsesProPrice(p)
+}
+
+func backfillOfficialDeepSeekResponsesCapabilities(p *ProviderEntry) {
+	if !isOfficialDeepSeekResponsesProvider(p) {
+		return
+	}
+	backfillOfficialDeepSeekEffortOverrides(p)
+}
+
+func backfillOfficialDeepSeekEffortOverrides(p *ProviderEntry) {
+	if p == nil {
+		return
+	}
+	capabilities := deepSeekV4EffortOverrides()
+	if model := strings.TrimSpace(p.Model); model != "" && len(p.Models) == 0 {
+		defaults, ok := capabilities[model]
+		if !ok || len(p.SupportedEfforts) > 0 {
+			return
+		}
+		p.SupportedEfforts = append([]string(nil), defaults.SupportedEfforts...)
+		if strings.TrimSpace(p.DefaultEffort) == "" {
+			p.DefaultEffort = defaults.DefaultEffort
+		}
+		return
+	}
+	if p.ModelOverrides == nil {
+		p.ModelOverrides = map[string]ProviderModelOverride{}
+	}
+	for model, defaults := range capabilities {
+		if !p.HasModel(model) {
+			continue
+		}
+		override := p.ModelOverrides[model]
+		if len(override.SupportedEfforts) == 0 {
+			override.SupportedEfforts = append([]string(nil), defaults.SupportedEfforts...)
+			if strings.TrimSpace(override.DefaultEffort) == "" {
+				override.DefaultEffort = defaults.DefaultEffort
+			}
+		}
+		p.ModelOverrides[model] = override
+	}
+}
+
+// backfillOfficialDeepSeekResponsesProPrice fills Prices[pro] when a legacy
+// singular Price would otherwise make Pro inherit the Flash list price.
+func backfillOfficialDeepSeekResponsesProPrice(p *ProviderEntry) {
+	if p == nil || !p.HasModel("deepseek-v4-pro") || p.Prices["deepseek-v4-pro"] != nil {
+		return
+	}
+	currency := p.ProviderBillingCurrency()
+	if currency == "" {
+		currency = "USD"
+	}
+	price := deepSeekV4PriceForModel(currency, "deepseek-v4-pro")
+	if price == nil {
+		return
+	}
+	if p.Prices == nil {
+		p.Prices = map[string]*provider.Pricing{}
+	}
+	p.Prices["deepseek-v4-pro"] = price
+}

internal/config/load.go

@@ -1641,17 +1641,17 @@ func normalizeOfficialDeepSeekModels(c *Config) {
 		}
 		switch strings.TrimSpace(p.Name) {
 		case "deepseek":
-			required := []string{"deepseek-v4-flash", "deepseek-v4-pro"}
-			if strings.EqualFold(strings.TrimSpace(p.Kind), "responses") {
-				required = required[:1]
-			}
-			ensureProviderModels(p, required, "deepseek-v4-flash")
+			ensureProviderModels(p, []string{"deepseek-v4-flash", "deepseek-v4-pro"}, "deepseek-v4-flash")
 		case "deepseek-flash":
 			ensureProviderModels(p, []string{"deepseek-v4-flash"}, "deepseek-v4-flash")
 		case "deepseek-pro":
 			ensureProviderModels(p, []string{"deepseek-v4-pro"}, "deepseek-v4-pro")
+		case "deepseek-responses":
+			ensureProviderModels(p, []string{"deepseek-v4-flash", "deepseek-v4-pro"}, "deepseek-v4-flash")
 		}
+		backfillOfficialDeepSeekResponsesModels(p)
 		backfillDeepSeekAnthropicCapabilities(p)
+		backfillOfficialDeepSeekResponsesCapabilities(p)
 	}
 }
 
@@ -1663,37 +1663,7 @@ func backfillDeepSeekAnthropicCapabilities(p *ProviderEntry) {
 	if strings.TrimSpace(p.Thinking) == "" {
 		p.Thinking = "enabled"
 	}
-	capabilities := map[string]ProviderModelOverride{
-		"deepseek-v4-flash": {SupportedEfforts: []string{"disabled", "low", "high", "max"}, DefaultEffort: "high"},
-		"deepseek-v4-pro":   {SupportedEfforts: []string{"disabled", "high", "max"}, DefaultEffort: "high"},
-	}
-	if model := strings.TrimSpace(p.Model); model != "" && len(p.Models) == 0 {
-		defaults, ok := capabilities[model]
-		if !ok || len(p.SupportedEfforts) > 0 {
-			return
-		}
-		p.SupportedEfforts = append([]string(nil), defaults.SupportedEfforts...)
-		if strings.TrimSpace(p.DefaultEffort) == "" {
-			p.DefaultEffort = defaults.DefaultEffort
-		}
-		return
-	}
-	if p.ModelOverrides == nil {
-		p.ModelOverrides = map[string]ProviderModelOverride{}
-	}
-	for model, defaults := range capabilities {
-		if !p.HasModel(model) {
-			continue
-		}
-		override := p.ModelOverrides[model]
-		if len(override.SupportedEfforts) == 0 {
-			override.SupportedEfforts = append([]string(nil), defaults.SupportedEfforts...)
-			if strings.TrimSpace(override.DefaultEffort) == "" {
-				override.DefaultEffort = defaults.DefaultEffort
-			}
-		}
-		p.ModelOverrides[model] = override
-	}
+	backfillOfficialDeepSeekEffortOverrides(p)
 }
 
 func officialProviderHost(baseURL string) string {
@@ -2039,21 +2009,18 @@ func ensureDeepSeekOfficialProvider(c *Config) {
 		return
 	}
 	entry := ProviderEntry{
-		Name:          "deepseek",
-		Kind:          "anthropic",
-		BaseURL:       deepSeekAnthropicBaseURL,
-		Models:        []string{"deepseek-v4-flash", "deepseek-v4-pro"},
-		Default:       "deepseek-v4-flash",
-		APIKeyEnv:     "DEEPSEEK_API_KEY",
-		BalanceURL:    "https://api.deepseek.com/user/balance",
-		Thinking:      "enabled",
-		WebSearch:     boolPointer(true),
-		ContextWindow: 1_000_000,
-		Prices:        deepSeekV4PricesForConfig(c),
-		ModelOverrides: map[string]ProviderModelOverride{
-			"deepseek-v4-flash": {SupportedEfforts: []string{"disabled", "low", "high", "max"}, DefaultEffort: "high"},
-			"deepseek-v4-pro":   {SupportedEfforts: []string{"disabled", "high", "max"}, DefaultEffort: "high"},
-		},
+		Name:           "deepseek",
+		Kind:           "anthropic",
+		BaseURL:        deepSeekAnthropicBaseURL,
+		Models:         []string{"deepseek-v4-flash", "deepseek-v4-pro"},
+		Default:        "deepseek-v4-flash",
+		APIKeyEnv:      "DEEPSEEK_API_KEY",
+		BalanceURL:     "https://api.deepseek.com/user/balance",
+		Thinking:       "enabled",
+		WebSearch:      boolPointer(true),
+		ContextWindow:  1_000_000,
+		Prices:         deepSeekV4PricesForConfig(c),
+		ModelOverrides: deepSeekV4EffortOverrides(),
 	}
 	legacyProviders := officialLegacyDeepSeekProviders(c)
 	if len(legacyProviders) > 0 {

internal/config/provider_presets.go

@@ -97,7 +97,6 @@ var (
 
 	minimaxMSeriesModels       = []string{"MiniMax-M3", "MiniMax-M2.7", "MiniMax-M2.7-highspeed"}
 	minimaxMSeriesVisionModels = []string{"MiniMax-M3"}
-	deepSeekResponsesModels    = []string{"deepseek-v4-flash"}
 
 	glmAPIModels       = []string{"glm-5.2", "glm-5.1", "glm-5", "glm-5-turbo", "glm-5v-turbo", "glm-4.7", "glm-4.7-flash", "glm-4.7-flashx", "glm-4.6", "glm-4.5", "glm-4.5-air", "glm-4.5-flash"}
 	glmAPIVisionModels = []string{"glm-5v-turbo"}
@@ -194,21 +193,18 @@ var curatedProviderPresets = []ProviderPreset{
 		Description: "Separate official DeepSeek Anthropic-compatible entry for Flash and Pro.",
 		KeyEnv:      "DEEPSEEK_API_KEY",
 		Entries: []ProviderEntry{{
-			Name:          "deepseek-anthropic",
-			Kind:          "anthropic",
-			BaseURL:       deepSeekAnthropicBaseURL,
-			Models:        deepSeekV4Models,
-			Default:       "deepseek-v4-flash",
-			APIKeyEnv:     "DEEPSEEK_API_KEY",
-			BalanceURL:    "https://api.deepseek.com/user/balance",
-			Thinking:      "enabled",
-			WebSearch:     boolPointer(true),
-			ContextWindow: 1_000_000,
-			Prices:        deepSeekV4PricesUSD(),
-			ModelOverrides: map[string]ProviderModelOverride{
-				"deepseek-v4-flash": {SupportedEfforts: []string{"disabled", "low", "high", "max"}, DefaultEffort: "high"},
-				"deepseek-v4-pro":   {SupportedEfforts: []string{"disabled", "high", "max"}, DefaultEffort: "high"},
-			},
+			Name:           "deepseek-anthropic",
+			Kind:           "anthropic",
+			BaseURL:        deepSeekAnthropicBaseURL,
+			Models:         deepSeekV4Models,
+			Default:        "deepseek-v4-flash",
+			APIKeyEnv:      "DEEPSEEK_API_KEY",
+			BalanceURL:     "https://api.deepseek.com/user/balance",
+			Thinking:       "enabled",
+			WebSearch:      boolPointer(true),
+			ContextWindow:  1_000_000,
+			Prices:         deepSeekV4PricesUSD(),
+			ModelOverrides: deepSeekV4EffortOverrides(),
 		}},
 	},
 	{
@@ -545,22 +541,21 @@ var curatedProviderPresets = []ProviderPreset{
 	{
 		ID:          "deepseek-responses",
 		Label:       "DeepSeek Official Responses API",
-		Description: "Official stateless DeepSeek Responses API for Flash with server-side web search.",
+		Description: "Official stateless DeepSeek Responses API for Flash and Pro with server-side web search.",
 		KeyEnv:      "DEEPSEEK_API_KEY",
 		Entries: []ProviderEntry{{
-			Name:             "deepseek-responses",
-			Kind:             "responses",
-			BaseURL:          "https://api.deepseek.com",
-			Models:           deepSeekResponsesModels,
-			Default:          "deepseek-v4-flash",
-			APIKeyEnv:        "DEEPSEEK_API_KEY",
-			BalanceURL:       "https://api.deepseek.com/user/balance",
-			ContextWindow:    1_000_000,
-			Price:            deepSeekV4FlashPriceUSD(),
-			ResponsesMode:    "stateless",
-			WebSearch:        boolPointer(true),
-			SupportedEfforts: []string{"low", "high", "max"},
-			DefaultEffort:    "high",
+			Name:           "deepseek-responses",
+			Kind:           "responses",
+			BaseURL:        "https://api.deepseek.com",
+			Models:         deepSeekV4Models,
+			Default:        "deepseek-v4-flash",
+			APIKeyEnv:      "DEEPSEEK_API_KEY",
+			BalanceURL:     "https://api.deepseek.com/user/balance",
+			ContextWindow:  1_000_000,
+			Prices:         deepSeekV4PricesUSD(),
+			ResponsesMode:  "stateless",
+			WebSearch:      boolPointer(true),
+			ModelOverrides: deepSeekV4EffortOverrides(),
 		}},
 	},
 	{

internal/config/provider_presets_test.go

@@ -179,7 +179,7 @@ func TestDeepSeekResponsesPresetMatchesOfficialSupport(t *testing.T) {
 	if entry.Kind != "responses" || entry.BaseURL != "https://api.deepseek.com" || entry.ResponsesMode != "stateless" {
 		t.Fatalf("deepseek responses endpoint = %+v", entry)
 	}
-	if len(entry.Models) != 1 || entry.Models[0] != "deepseek-v4-flash" || entry.Default != "deepseek-v4-flash" {
+	if !entry.HasModel("deepseek-v4-flash") || !entry.HasModel("deepseek-v4-pro") || entry.Default != "deepseek-v4-flash" {
 		t.Fatalf("deepseek responses models = %v default=%q", entry.Models, entry.Default)
 	}
 	if entry.ModelsURL != "" {
@@ -188,6 +188,24 @@ func TestDeepSeekResponsesPresetMatchesOfficialSupport(t *testing.T) {
 	if !EffectiveWebSearch(&entry) || entry.Vision || entry.VisionModels != nil {
 		t.Fatalf("deepseek responses capabilities = web_search:%t vision:%t vision_models:%v", EffectiveWebSearch(&entry), entry.Vision, entry.VisionModels)
 	}
+	var cfg Config
+	if err := cfg.UpsertProvider(entry); err != nil {
+		t.Fatalf("UpsertProvider: %v", err)
+	}
+	flash, ok := cfg.ResolveModel("deepseek-responses/deepseek-v4-flash")
+	if !ok {
+		t.Fatal("Flash model did not resolve")
+	}
+	pro, ok := cfg.ResolveModel("deepseek-responses/deepseek-v4-pro")
+	if !ok {
+		t.Fatal("Pro model did not resolve")
+	}
+	if cap := EffortCapabilityForEntry(flash); cap.Default != "high" || !containsString(cap.Levels, "disabled") || !containsString(cap.Levels, "low") || !containsString(cap.Levels, "max") {
+		t.Fatalf("Flash effort capability = %+v", cap)
+	}
+	if cap := EffortCapabilityForEntry(pro); cap.Default != "high" || containsString(cap.Levels, "low") || !containsString(cap.Levels, "max") {
+		t.Fatalf("Pro effort capability = %+v", cap)
+	}
 }
 
 func TestCuratedProviderPresetsDisplayOrder(t *testing.T) {

internal/control/branches_test.go

@@ -2,6 +2,7 @@ package control
 
 import (
 	"context"
+	"os"
 	"path/filepath"
 	"strings"
 	"testing"
@@ -9,6 +10,7 @@ import (
 	"reasonix/internal/agent"
 	"reasonix/internal/event"
 	"reasonix/internal/provider"
+	"reasonix/internal/store"
 	"reasonix/internal/tool"
 )
 
@@ -57,6 +59,40 @@ func TestBranchAndSwitch(t *testing.T) {
 	}
 }
 
+func TestSnapshotExternalRemovalMovesOnceToStableRecovery(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "root.jsonl")
+	session := agent.NewSession("sys")
+	session.Add(provider.Message{Role: provider.RoleUser, Content: "keep me"})
+	exec := agent.New(nil, nil, session, agent.Options{}, event.Discard)
+	c := New(Options{Executor: exec, SessionDir: dir, SessionPath: path, Label: "test"})
+	if err := c.Snapshot(); err != nil {
+		t.Fatal(err)
+	}
+	for _, artifact := range append([]string{path}, store.SessionSidecarFiles(path)...) {
+		if artifact != "" {
+			_ = os.Remove(artifact)
+		}
+	}
+	session.Add(provider.Message{Role: provider.RoleAssistant, Content: "still here"})
+	if err := c.Snapshot(); err != nil {
+		t.Fatalf("snapshot after external removal: %v", err)
+	}
+	recovered := c.SessionPath()
+	if recovered == path || recovered == "" {
+		t.Fatalf("session path = %q, want recovery path", recovered)
+	}
+	if _, err := os.Stat(path); !os.IsNotExist(err) {
+		t.Fatalf("deleted original was recreated: %v", err)
+	}
+	if err := c.Snapshot(); err != nil {
+		t.Fatalf("second recovery snapshot: %v", err)
+	}
+	if got := c.SessionPath(); got != recovered {
+		t.Fatalf("recovery fork storm: %q -> %q", recovered, got)
+	}
+}
+
 func TestSwitchBranchRejectsCleanupPending(t *testing.T) {
 	dir := t.TempDir()
 	exec := agent.New(nil, nil, agent.NewSession("sys"), agent.Options{}, event.Discard)

internal/control/controller.go

@@ -3844,6 +3844,17 @@ func (c *Controller) snapshotWithDurability(markActivity, forceRewrite, shutdown
 			err = nil
 		}
 	}
+	if err != nil {
+		if errors.Is(err, agent.ErrSessionExternallyRemoved) {
+			recoveredPath, recoverErr := c.recoverExternallyRemovedSession(path, err)
+			if recoverErr != nil {
+				return false, recoverErr
+			}
+			path = recoveredPath
+			s = c.executor.Session()
+			err = nil
+		}
+	}
 	if err != nil {
 		if !errors.Is(err, agent.ErrSessionSnapshotConflict) {
 			return false, err
@@ -3898,6 +3909,35 @@ func (c *Controller) snapshotWithDurability(markActivity, forceRewrite, shutdown
 	return transcriptDurable, nil
 }
 
+func (c *Controller) recoverExternallyRemovedSession(path string, saveErr error) (string, error) {
+	if c.executor == nil || strings.TrimSpace(path) == "" {
+		return "", saveErr
+	}
+	const reason = "session removed while open"
+	req := SessionRecoveryRequest{OriginalPath: path, Reason: reason, Mode: "external-removal"}
+	meta := agent.BranchMeta{}
+	if c.sessionRecoveryMeta != nil {
+		meta = c.sessionRecoveryMeta(req)
+	}
+	info, err := c.executor.Session().SaveConflictRecoveryBranch(agent.RecoveryBranchOptions{
+		OriginalPath: path,
+		Reason:       reason,
+		BranchMeta:   meta,
+	})
+	if err != nil {
+		return "", fmt.Errorf("preserve externally removed session: %w", err)
+	}
+	if err := c.commitRecoveredSession(path, reason, info); err != nil {
+		return "", err
+	}
+	appendSnapshotConflictDiagnostic(path, "external-removal", "moved_to_stable_recovery", saveErr, info.Path, info.Existing)
+	slog.Warn("controller: active session was removed externally; moved runtime to stable recovery path",
+		"path", path, "recovery", info.Path, "existing", info.Existing)
+	c.sink.Emit(sessionRecoveryNotice(event.NoticeCodeSessionRecoveryForked,
+		"the open session file was removed outside Reasonix; your active conversation was preserved as one recovery copy"))
+	return info.Path, nil
+}
+
 // snapshotConflictLogAttrs flattens a snapshot-conflict error into slog attrs.
 // Field reports of #6069-class "session changed on disk" spam are only
 // diagnosable when the logs say which trigger fired and what the revision

internal/evidence/effects.go

@@ -0,0 +1,89 @@
+package evidence
+
+import (
+	"encoding/json"
+	"strings"
+
+	"reasonix/internal/shellsafe"
+)
+
+// ToolEffects projects shell effects onto policy and evidence boundaries.
+type ToolEffects struct {
+	StateMutation, WorkspaceMutation, ContentMutation, RepositoryMutation bool
+	Known                                                                 bool
+	Reason                                                                string
+}
+
+// ClassifyToolCall returns durable effects for one concrete invocation.
+func ClassifyToolCall(toolName string, args json.RawMessage, readOnly bool) ToolEffects {
+	name := strings.ToLower(strings.TrimSpace(toolName))
+	if name == "bash" || name == "shell" {
+		effects, _ := ClassifyBashToolCall(args)
+		return effects
+	}
+	if readOnly || IsNonMutationMetaTool(toolName) {
+		return ToolEffects{Known: true}
+	}
+	switch name {
+	case "ask", "todo_write", "complete_step", "bash_output", "wait":
+		return ToolEffects{Known: true}
+	default:
+		return ToolEffects{StateMutation: true, WorkspaceMutation: true, ContentMutation: true, Known: true, Reason: "workspace content write by a writer-capable tool"}
+	}
+}
+
+// ClassifyBashToolCall parses once and returns effects plus permission trust.
+func ClassifyBashToolCall(args json.RawMessage) (ToolEffects, bool) {
+	var fields map[string]json.RawMessage
+	if err := json.Unmarshal(args, &fields); err != nil {
+		return unknownToolEffects("invalid shell arguments"), false
+	}
+	command := stringField(fields, "command")
+	effect := shellsafe.ClassifyBash(command)
+	if effect.Certainty == shellsafe.EffectKnown {
+		return ToolEffects{
+			StateMutation: effect.AnyMutation(), WorkspaceMutation: effect.WorkspaceMutation(),
+			ContentMutation: effect.ContentMutation(), RepositoryMutation: effect.RepositoryMutation(),
+			Known: true, Reason: commandEffectReason(effect),
+		}, effect.IsPermissionReader()
+	}
+	// Unknown syntax stays fail-closed unless the host recognized a verifier
+	// such as `go test` that ClassifyBash does not model as a known reader.
+	if bashCommandIsVerification(command) {
+		return ToolEffects{Known: true}, false
+	}
+	return unknownToolEffects(effect.Reason), false
+}
+
+func commandEffectReason(effect shellsafe.CommandEffect) string {
+	domain := ""
+	switch {
+	case effect.Writes&shellsafe.WriteWorkspaceContent != 0:
+		domain = "workspace content write"
+	case effect.Writes&shellsafe.WriteRepositoryMetadata != 0:
+		domain = "repository metadata write"
+	case effect.Writes&shellsafe.WriteHostState != 0:
+		domain = "host state write"
+	case effect.Writes&shellsafe.WriteExternalState != 0:
+		domain = "external state write"
+	}
+	if domain == "" {
+		return effect.Reason
+	}
+	if effect.CommandFamily == "" {
+		return domain
+	}
+	return domain + " by " + effect.CommandFamily
+}
+
+func unknownToolEffects(reason string) ToolEffects {
+	if strings.TrimSpace(reason) == "" {
+		reason = "tool effects are not statically known"
+	}
+	return ToolEffects{StateMutation: true, WorkspaceMutation: true, ContentMutation: true, Reason: reason}
+}
+
+// ToolCallMutates is the compatibility projection for durable state changes.
+func ToolCallMutates(toolName string, args json.RawMessage, readOnly bool) bool {
+	return ClassifyToolCall(toolName, args, readOnly).StateMutation
+}

internal/evidence/effects_test.go

@@ -0,0 +1,68 @@
+package evidence
+
+import (
+	"encoding/json"
+	"os"
+	"testing"
+)
+
+func TestEvidenceConsumesSharedCommandEffectMatrix(t *testing.T) {
+	raw, err := os.ReadFile("../shellsafe/testdata/command_effects.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var cases []struct {
+		Name, Command                      string
+		Certainty                          string
+		TaskPolicyBlocked, ContentMutation bool
+	}
+	if err := json.Unmarshal(raw, &cases); err != nil {
+		t.Fatal(err)
+	}
+	for _, tc := range cases {
+		t.Run(tc.Name, func(t *testing.T) {
+			args, _ := json.Marshal(map[string]string{"command": tc.Command})
+			got := ClassifyToolCall("bash", args, false)
+			if got.Known != (tc.Certainty == "known") || got.StateMutation != tc.TaskPolicyBlocked || got.ContentMutation != tc.ContentMutation {
+				t.Fatalf("ClassifyToolCall(%q) = %+v, matrix=%+v", tc.Command, got, tc)
+			}
+		})
+	}
+}
+
+func TestClassifyToolCallSeparatesMutationDomains(t *testing.T) {
+	tests := []struct {
+		name, tool, args string
+		readOnly         bool
+		want             ToolEffects
+	}{
+		{"branch listing", "bash", `{"command":"git branch -a"}`, false, ToolEffects{Known: true}},
+		{"tag creation", "bash", `{"command":"git tag v1.2.3"}`, true, ToolEffects{Known: true, StateMutation: true, WorkspaceMutation: true, RepositoryMutation: true}},
+		{"pure commit", "bash", `{"command":"git commit -q -m checkpoint"}`, false, ToolEffects{Known: true, StateMutation: true, WorkspaceMutation: true, RepositoryMutation: true}},
+		{"commit all", "bash", `{"command":"git commit -am checkpoint"}`, false, ToolEffects{Known: true, StateMutation: true, WorkspaceMutation: true, ContentMutation: true, RepositoryMutation: true}},
+		{"host clock", "bash", `{"command":"date --set tomorrow"}`, false, ToolEffects{Known: true, StateMutation: true}},
+		{"audit fix", "bash", `{"command":"npm audit fix"}`, false, ToolEffects{Known: true, StateMutation: true, WorkspaceMutation: true, ContentMutation: true}},
+		{"verification", "bash", `{"command":"go test ./..."}`, false, ToolEffects{Known: true}},
+		{"env prefixed test", "bash", `{"command":"GOROOT=/x go test ./..."}`, false, ToolEffects{Known: true}},
+		{"unknown shell", "bash", `{"command":"custom-tool --run"}`, false, ToolEffects{StateMutation: true, WorkspaceMutation: true, ContentMutation: true}},
+		{"trusted reader", "read_file", `{}`, true, ToolEffects{Known: true}},
+		{"generic writer", "edit_file", `{}`, false, ToolEffects{Known: true, StateMutation: true, WorkspaceMutation: true, ContentMutation: true}},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := ClassifyToolCall(tt.tool, json.RawMessage(tt.args), tt.readOnly)
+			got.Reason, tt.want.Reason = "", ""
+			if got != tt.want {
+				t.Fatalf("ClassifyToolCall(%q, %s) = %+v, want %+v", tt.tool, tt.args, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestReceiptMutationTracksContentNotRepositoryCement(t *testing.T) {
+	pure := ReceiptFromToolCall("bash", json.RawMessage(`{"command":"git commit -m checkpoint"}`), true, false)
+	all := ReceiptFromToolCall("bash", json.RawMessage(`{"command":"git commit -am checkpoint"}`), true, false)
+	if pure.Mutation || !all.Mutation {
+		t.Fatalf("commit receipt domains: pure=%+v all=%+v", pure, all)
+	}
+}

internal/evidence/env_prefix_test.go

@@ -0,0 +1,25 @@
+package evidence
+
+import "testing"
+
+func TestEnvPrefixVerification(t *testing.T) {
+	cases := map[string]bool{
+		"go test ./internal/evidence/":                   true,
+		"go test ./internal/evidence/ -count=1":          true,
+		"GOROOT=/x go test ./internal/evidence/":         true,
+		"GOROOT=/x PATH=/y go test ./internal/evidence/": true,
+		"env GOROOT=/x go test ./internal/evidence/":     true,
+		"cd /tmp && go test ./internal/evidence/":        true,
+		"go test ./internal/evidence/ 2>&1 | tail -3":    true,
+		"GOROOT=/x rm -rf /":                             false,
+		"GOROOT=/x":                                      false,
+		"FOO=$(whoami) go test ./internal/evidence/":     false,
+		"env -i go test ./internal/evidence/":            false,
+		"CARGO_HOME=/y cargo test":                       true,
+	}
+	for c, want := range cases {
+		if got := IsDeliveryVerificationCommand(c); got != want {
+			t.Errorf("IsDeliveryVerificationCommand(%q) = %v, want %v", c, got, want)
+		}
+	}
+}

internal/evidence/evidence.go

@@ -1513,11 +1513,15 @@ func failedSessionCallIDs(msgs []provider.Message) map[string]bool {
 }
 
 func ReceiptFromToolCall(toolName string, args json.RawMessage, success bool, readOnly bool) Receipt {
+	effects := ClassifyToolCall(toolName, args, readOnly)
 	r := Receipt{
 		ToolName: toolName,
 		Args:     args,
 		Success:  success,
-		Mutation: ToolCallMutates(toolName, args, readOnly),
+		// Receipt.Mutation is delivery content debt. Repository-only state
+		// transitions such as a pure commit remain guarded writers, but do not
+		// force another content review pass by themselves.
+		Mutation: effects.ContentMutation,
 	}
 
 	var fields map[string]json.RawMessage
@@ -1571,33 +1575,6 @@ func ToolCallPaths(args json.RawMessage) []string {
 	return out
 }
 
-// ToolCallMutates is the delivery profile's conservative state-change
-// classifier. Trusted read-only tools never mutate. Meta tools that only
-// delegate (task, run_skill, review, …) never mutate by themselves — real
-// writes arrive via child evidence merge. Writer-capable tools do mutate,
-// except for bash commands that the host can prove are inspection or
-// verification commands.
-func ToolCallMutates(toolName string, args json.RawMessage, readOnly bool) bool {
-	if readOnly {
-		return false
-	}
-	if IsNonMutationMetaTool(toolName) {
-		return false
-	}
-	switch toolName {
-	case "ask", "todo_write", "complete_step", "bash_output", "wait":
-		return false
-	case "bash":
-		var fields map[string]json.RawMessage
-		if err := json.Unmarshal(args, &fields); err != nil {
-			return true
-		}
-		return bashMayMutate(stringField(fields, "command"))
-	default:
-		return true
-	}
-}
-
 // ToolCallRequiresDeliveryCriteria reports whether a call begins execution
 // work that needs an acceptance contract. Mutations always qualify; verification
 // commands also qualify even though they are intentionally not mutations.
@@ -1813,9 +1790,7 @@ func bashContainsVerificationSegment(command string) bool {
 		return false
 	}
 	for _, segment := range segments {
-		normalized, _ := shellsafe.NormalizeBashSafeRedirectsForMatch(segment)
-		fields, malformed := shellparse.StaticFields(normalized)
-		if malformed == "" && bashSegmentIsVerification(fields) {
+		if fields, ok := bashStaticArgv(segment); ok && bashSegmentIsVerification(fields) {
 			return true
 		}
 	}
@@ -1832,18 +1807,14 @@ func bashMayMutate(command string) bool {
 		return true
 	}
 	for _, segment := range segments {
-		normalized, safeRedirects := shellsafe.NormalizeBashSafeRedirectsForMatch(segment)
-		if !safeRedirects {
-			return true
+		normalized, _ := shellsafe.NormalizeBashSafeRedirectsForMatch(segment)
+		if normalized == "" {
+			normalized = segment
 		}
-		if staticFields, malformed := shellparse.StaticFields(normalized); malformed == "" && len(staticFields) > 0 && bashSegmentIsVerification(staticFields) {
+		if fields, ok := bashStaticArgv(normalized); ok && bashSegmentIsVerification(fields) {
 			continue
 		}
-		base, sub, fields, workspaceNonMutating := shellsafe.ClassifyWorkspaceNonMutatingCommand(normalized)
-		if !workspaceNonMutating {
-			return true
-		}
-		if bashReadOnlyCommandWrites(base, sub, fields) {
+		if shellsafe.ClassifyBash(segment).AnyMutation() {
 			return true
 		}
 	}
@@ -1865,21 +1836,29 @@ func bashCommandIsVerification(command string) bool {
 		if !safeRedirects {
 			return false
 		}
-		fields, malformed := shellparse.StaticFields(normalized)
-		if malformed != "" || len(fields) == 0 {
+		fields, ok := bashStaticArgv(normalized)
+		if !ok {
 			return false
 		}
 		if bashSegmentIsVerification(fields) {
 			found = true
 			continue
 		}
-		if _, _, readOnly := shellsafe.CommandIsReadOnly(normalized); !readOnly {
+		if shellsafe.ClassifyBash(normalized).AnyMutation() {
 			return false
 		}
 	}
 	return found
 }
 
+func bashStaticArgv(command string) ([]string, bool) {
+	if fields, _, ok := shellsafe.CommandArgv(command); ok {
+		return fields, true
+	}
+	fields, malformed := shellparse.StaticFields(command)
+	return fields, malformed == "" && len(fields) > 0
+}
+
 // IsDeliveryVerificationCommand reports whether command is a host-recognized
 // verification command for delivery finalization. Keep complete_step and the
 // final-readiness gate on this single classifier so a sign-off cannot claim a
@@ -2195,34 +2174,6 @@ func nodeTestFlagWritesFile(arg string) bool {
 	}
 }
 
-func bashReadOnlyCommandWrites(base, sub string, fields []string) bool {
-	args := fields[1:]
-	if sub != "" && len(args) > 0 {
-		args = args[1:]
-	}
-	switch base {
-	case "find":
-		return hasCommandArg(args, "-exec", "-execdir", "-delete", "-ok", "-okdir", "-fls", "-fprint", "-fprint0", "-fprintf")
-	case "sort":
-		for _, arg := range args {
-			if arg == "-o" || arg == "--output" || strings.HasPrefix(arg, "--output=") || strings.HasPrefix(arg, "-o") {
-				return true
-			}
-		}
-	case "git":
-		if sub == "diff" || sub == "show" || sub == "log" {
-			for _, arg := range args {
-				if arg == "--output" || strings.HasPrefix(arg, "--output=") {
-					return true
-				}
-			}
-		}
-	case "go":
-		return sub == "env" && hasCommandArg(args, "-w", "-u")
-	}
-	return false
-}
-
 func hasCommandArg(args []string, candidates ...string) bool {
 	for _, arg := range args {
 		for _, candidate := range candidates {

internal/evidence/outcome.go

@@ -173,7 +173,7 @@ func (t *OutcomeTracker) noteMutatedPaths(paths []string) {
 func (t *OutcomeTracker) commandExercisesMutation(command string) bool {
 	// Inspecting a mutated file (cat/grep/head) cannot falsify anything; only
 	// a command that can execute it discriminates.
-	if _, _, readOnly := shellsafe.CommandIsReadOnly(command); readOnly {
+	if !shellsafe.ClassifyBash(command).AnyMutation() {
 		return false
 	}
 	for base := range t.mutatedBases {
@@ -202,22 +202,36 @@ func (t *OutcomeTracker) scoreReceipt(r Receipt, s *OutcomeSample) {
 	case r.Success && (r.StepProof || r.TodoStep != nil || len(r.Todos) > 0):
 		// Bookkeeping moves no outcome dimension.
 	case r.Success && r.Read && r.OutputBytes > 0 && len(r.Paths) > 0:
+		fresh := 0
 		for _, path := range r.Paths {
 			if path == "" || t.readPaths[path] {
 				continue
 			}
 			t.readPaths[path] = true
-			s.Exploration++
+			fresh++
 		}
+		// A path already read can still answer a question never asked: a new
+		// grep pattern over the same package, the next window of a long file.
+		if newQuestion := t.noteQuestion(r); fresh == 0 && newQuestion {
+			fresh = 1
+		}
+		s.Exploration += fresh
 	case r.Success:
-		sig := r.ToolName + "\x00" + string(r.Args)
-		if !t.actions[sig] {
-			t.actions[sig] = true
+		if t.noteQuestion(r) {
 			s.Exploration++
 		}
 	}
 }
 
+func (t *OutcomeTracker) noteQuestion(r Receipt) bool {
+	sig := r.ToolName + "\x00" + string(r.Args)
+	if t.actions[sig] {
+		return false
+	}
+	t.actions[sig] = true
+	return true
+}
+
 func (t *OutcomeTracker) scoreCommand(command string, r Receipt, s *OutcomeSample) {
 	if r.Success && (r.Mutation || r.Write) {
 		s.Churn++

internal/evidence/progress.go

@@ -87,30 +87,38 @@ func (t *ProgressTracker) scoreReceipt(r Receipt) int {
 	case r.Success && (r.StepProof || r.TodoStep != nil || len(r.Todos) > 0):
 		return gainTaskProgress
 	case r.Success && r.Read && r.OutputBytes > 0 && len(r.Paths) > 0:
-		return t.scoreReads(r.Paths)
+		return t.scoreReads(r)
 	case r.Success:
-		// Unknown tools (MCP, custom): a first (tool, args) call is evidence;
-		// resending the identical call is not.
-		sig := r.ToolName + "\x00" + string(r.Args)
-		if t.actionSigs[sig] {
-			return 0
+		if t.noteQuestion(r) {
+			return gainNewAction
 		}
-		t.actionSigs[sig] = true
-		return gainNewAction
+		return 0
 	default:
 		return 0
 	}
 }
 
-func (t *ProgressTracker) scoreReads(paths []string) int {
+func (t *ProgressTracker) noteQuestion(r Receipt) bool {
+	sig := r.ToolName + "\x00" + string(r.Args)
+	if t.actionSigs[sig] {
+		return false
+	}
+	t.actionSigs[sig] = true
+	return true
+}
+
+func (t *ProgressTracker) scoreReads(r Receipt) int {
 	gain := 0
-	for _, path := range paths {
+	for _, path := range r.Paths {
 		if path == "" || t.readPaths[path] {
 			continue
 		}
 		t.readPaths[path] = true
 		gain += gainNewRead
 	}
+	if newQuestion := t.noteQuestion(r); gain == 0 && newQuestion {
+		return gainNewRead
+	}
 	return gain
 }
 

internal/evidence/read_novelty_test.go

@@ -0,0 +1,81 @@
+package evidence
+
+import (
+	"encoding/json"
+	"fmt"
+	"testing"
+)
+
+func grepReceipt(pattern, path string) Receipt {
+	args := json.RawMessage(fmt.Sprintf(`{"pattern":%q,"path":%q}`, pattern, path))
+	r := ReceiptFromToolCall("grep", args, true, true)
+	r.OutputBytes = 64
+	return r
+}
+
+func windowReceipt(path string, offset int) Receipt {
+	args := json.RawMessage(fmt.Sprintf(`{"path":%q,"offset":%d,"limit":300}`, path, offset))
+	r := ReceiptFromToolCall("read_file", args, true, true)
+	r.OutputBytes = 64
+	return r
+}
+
+// Read novelty used to be keyed on the path alone, so the two most common
+// investigation moves — grepping one package for a second symbol, paging
+// through a long file — scored as repeats from the second round on, and a turn
+// doing exactly that was told it had produced no new evidence.
+func TestProgressTrackerScoresTheQuestionNotJustThePath(t *testing.T) {
+	tr := NewProgressTracker()
+
+	if got := tr.ScoreRound([]Receipt{grepReceipt("Compose", "internal/agent")}); got != gainNewRead {
+		t.Fatalf("first grep = %d, want %d", got, gainNewRead)
+	}
+	if got := tr.ScoreRound([]Receipt{grepReceipt("Receipt", "internal/agent")}); got != gainNewRead {
+		t.Fatalf("new pattern over a read path = %d, want %d", got, gainNewRead)
+	}
+	if got := tr.ScoreRound([]Receipt{grepReceipt("Receipt", "internal/agent")}); got != 0 {
+		t.Fatalf("identical grep = %d, want 0", got)
+	}
+
+	if got := tr.ScoreRound([]Receipt{windowReceipt("agent.go", 0)}); got != gainNewRead {
+		t.Fatalf("first window = %d, want %d", got, gainNewRead)
+	}
+	if got := tr.ScoreRound([]Receipt{windowReceipt("agent.go", 300)}); got != gainNewRead {
+		t.Fatalf("next window of the same file = %d, want %d", got, gainNewRead)
+	}
+	if got := tr.ScoreRound([]Receipt{windowReceipt("agent.go", 300)}); got != 0 {
+		t.Fatalf("identical window = %d, want 0", got)
+	}
+
+	// A first read of a new path still counts once, not twice. It needs a fresh
+	// tracker: past explorationRunLimit look-only rounds the run stops counting
+	// whatever it finds, which is the separate cliff this change does not touch.
+	fresh := NewProgressTracker()
+	first := readReceipt("new.go")
+	first.OutputBytes = 64
+	if got := fresh.ScoreRound([]Receipt{first}); got != gainNewRead {
+		t.Fatalf("new path = %d, want %d", got, gainNewRead)
+	}
+}
+
+// The shadow scorer keys novelty the same way, so the two never disagree about
+// what counts as a repeat.
+func TestOutcomeTrackerScoresTheQuestionNotJustThePath(t *testing.T) {
+	tr := NewOutcomeTracker()
+
+	if s := tr.ScoreRound([]Receipt{grepReceipt("Compose", "internal/agent")}); s.Exploration != 1 {
+		t.Fatalf("first grep = %+v, want exploration 1", s)
+	}
+	if s := tr.ScoreRound([]Receipt{grepReceipt("Receipt", "internal/agent")}); s.Exploration != 1 {
+		t.Fatalf("new pattern over a read path = %+v, want exploration 1", s)
+	}
+	if s := tr.ScoreRound([]Receipt{grepReceipt("Receipt", "internal/agent")}); s.Exploration != 0 {
+		t.Fatalf("identical grep = %+v, want exploration 0", s)
+	}
+	if s := tr.ScoreRound([]Receipt{windowReceipt("agent.go", 0)}); s.Exploration != 1 {
+		t.Fatalf("first window = %+v, want exploration 1", s)
+	}
+	if s := tr.ScoreRound([]Receipt{windowReceipt("agent.go", 300)}); s.Exploration != 1 {
+		t.Fatalf("next window of the same file = %+v, want exploration 1", s)
+	}
+}

internal/permission/bash_readonly.go

@@ -2,7 +2,6 @@ package permission
 
 import (
 	"encoding/json"
-	"slices"
 	"strings"
 
 	"reasonix/internal/shellsafe"
@@ -29,21 +28,10 @@ func BashCommandIsReadOnly(args json.RawMessage) bool {
 
 // isReadOnlyBashSubject returns true when a bash command is a known read-only
 // operation. The subject is the JSON arg value extracted by Subject() — for bash
-// it is the raw command string. Command membership comes from the shared
-// shellsafe tables (the shared command-classification source, #5341); the
-// argument rigor below is permission-specific.
+// it is the raw command string. Both command membership and argument effects
+// come from shellsafe so permission and mutation accounting cannot drift.
 func isReadOnlyBashSubject(subject string) bool {
-	if normalized, ok := normalizeBashSafeRedirectsForMatch(subject); ok {
-		subject = normalized
-	}
-	base, sub, fields, ok := shellsafe.ClassifyReadOnlyCommand(subject)
-	if !ok {
-		return false
-	}
-	if sub == "" {
-		return !hasUnsafeReadOnlyArgs(base, fields[1:])
-	}
-	return !hasUnsafePrefixArgs(base, sub, fields[2:])
+	return shellsafe.ClassifyBash(subject).IsPermissionReader()
 }
 
 // containsShellSyntax delegates to the shared classifier; retained for the other
@@ -52,85 +40,6 @@ func containsShellSyntax(cmd string) bool {
 	return shellsafe.ContainsShellSyntax(cmd)
 }
 
-func hasUnsafeReadOnlyArgs(base string, args []string) bool {
-	switch base {
-	case "find":
-		return hasAnyArg(args, "-exec", "-execdir", "-delete", "-ok", "-okdir", "-fls", "-fprint", "-fprint0", "-fprintf")
-	case "sed":
-		for _, arg := range args {
-			if strings.HasPrefix(arg, "-i") || strings.HasPrefix(arg, "--in-place") {
-				return true
-			}
-		}
-	case "sort":
-		return hasArgWithPrefix(args, "-o") || hasAnyArg(args, "--output") || hasArgWithPrefix(args, "--output=")
-	}
-	return false
-}
-
-func hasUnsafePrefixArgs(base, subcmd string, args []string) bool {
-	switch base {
-	case "git":
-		switch subcmd {
-		case "diff", "show", "log":
-			return hasAnyArg(args, "--output") || hasArgWithPrefix(args, "--output=")
-		case "tag":
-			// Bare `git tag` lists; with a name it creates one, and -d deletes.
-			return !gitTagIsListing(args)
-		}
-	case "go":
-		if subcmd == "env" {
-			return hasAnyArg(args, "-w", "-u")
-		}
-	}
-	return false
-}
-
-// gitTagIsListing reports whether a `git tag` invocation only lists tags. A
-// bare `git tag` lists; a name creates one and -d deletes, so anything that
-// isn't an explicit listing form writes the ref namespace.
-func gitTagIsListing(args []string) bool {
-	listing := false
-	var operands []string
-	for _, arg := range args {
-		switch {
-		case arg == "-l" || arg == "--list":
-			listing = true
-		case arg == "-d" || arg == "--delete" || arg == "-a" || arg == "-s" || arg == "-f" || arg == "--force" || arg == "-m" || arg == "-F":
-			return false
-		case strings.HasPrefix(arg, "-"):
-			// Remaining flags (-n, --sort=, --format=, --contains, …) are output
-			// shaping; unknown ones fail closed below only when paired with an
-			// operand, which is the create/delete form.
-			continue
-		default:
-			operands = append(operands, arg)
-		}
-	}
-	if listing {
-		return true // operands are shell patterns for the listing filter
-	}
-	return len(operands) == 0
-}
-
-func hasArgWithPrefix(args []string, prefix string) bool {
-	for _, arg := range args {
-		if strings.HasPrefix(arg, prefix) {
-			return true
-		}
-	}
-	return false
-}
-
-func hasAnyArg(args []string, unsafe ...string) bool {
-	for _, arg := range args {
-		if slices.Contains(unsafe, arg) {
-			return true
-		}
-	}
-	return false
-}
-
 // dangerousBashPatterns are glob-like patterns that match destructive
 // commands. Used only for a UI warning — the deny list is the actual
 // enforcement mechanism.

internal/permission/bash_readonly_test.go

@@ -46,7 +46,8 @@ func TestIsReadOnlyBashSubject(t *testing.T) {
 		{"git log >NUL", true},
 		{"git log 2>&1", true},
 		{"git log &>/dev/null", true},
-		{"git remote", false},
+		{"git remote", true},
+		{"git remote -v", true},
 		{"git remote add origin [email protected]:x/y", false},
 		{"git config --global user.name Xinwei", false},
 		{"git stash", false},
@@ -74,8 +75,11 @@ func TestIsReadOnlyBashSubject(t *testing.T) {
 		{"rm -rf /", false},
 		{"env rm -rf /", false},
 		{"git commit -m 'msg'", false},
-		{"git branch", false},
+		{"git branch", true},
+		{"git branch -a", true},
 		{"git branch feature/new", false},
+		{"git config --edit", false},
+		{"git config --global -e", false},
 		{"git push", false},
 		{"git push --force", false},
 		{"cd /tmp && rm file.txt", false},

internal/recovery/rules.go

@@ -199,15 +199,10 @@ func IsDiagnosticSuccess(obs Observation) bool {
 	switch strings.TrimSpace(obs.Tool) {
 	case "bash":
 		cmd := commandFromArgs(obs.Args)
-		base, _, readOnly := shellsafe.CommandIsReadOnly(cmd)
-		if !readOnly {
+		if shellsafe.ClassifyBash(cmd).AnyMutation() {
 			return false
 		}
-		switch strings.ToLower(filepath.Base(base)) {
-		case "ls", "rg", "grep", "find", "cat", "head", "tail", "wc", "file", "stat", "pwd", "which", "type":
-			return true
-		}
-		return true // other host-proven read-only bash diagnostics
+		return true
 	case "read_file", "grep", "glob", "ls", "code_index", "codeindex":
 		return obs.ReadOnly
 	default:
@@ -644,7 +639,7 @@ func commandFieldsKnownSafeMutation(fields []string) bool {
 	// A coarse host mutation bit must not turn a statically proven read-only
 	// diagnostic into a confirmation. Destructive argument forms were rejected
 	// before reaching this point.
-	if _, _, readOnly := shellsafe.CommandIsReadOnly(strings.Join(fields, " ")); readOnly {
+	if !shellsafe.ClassifyBash(strings.Join(fields, " ")).AnyMutation() {
 		return true
 	}
 	return false

internal/sessioncatalog/catalog.go

@@ -170,14 +170,26 @@ func (c *Catalog) refreshCounts(ctx context.Context) {
 	if c == nil || c.db == nil {
 		return
 	}
-	var indexed, pending, total int64
+	var indexed, pending, total, physical, logical, groups, branches, diverged, cleanup int64
 	_ = c.db.QueryRowContext(ctx, `SELECT COUNT(*) FROM catalog_sessions`).Scan(&indexed)
 	_ = c.db.QueryRowContext(ctx, `SELECT COUNT(*) FROM catalog_sessions WHERE turns_state='unknown'`).Scan(&pending)
 	_ = c.db.QueryRowContext(ctx, `SELECT COALESCE(SUM(total), 0) FROM catalog_directories`).Scan(&total)
+	_ = c.db.QueryRowContext(ctx, `SELECT COUNT(*) FROM catalog_sessions WHERE missing_since=0`).Scan(&physical)
+	_ = c.db.QueryRowContext(ctx, `SELECT COUNT(*) FROM catalog_topics`).Scan(&logical)
+	_ = c.db.QueryRowContext(ctx, `SELECT COUNT(DISTINCT recovery_group_id) FROM catalog_sessions WHERE recovered=1 AND recovery_group_id<>'' AND missing_since=0`).Scan(&groups)
+	_ = c.db.QueryRowContext(ctx, `SELECT COUNT(*) FROM catalog_sessions WHERE recovered=1 AND missing_since=0`).Scan(&branches)
+	_ = c.db.QueryRowContext(ctx, `SELECT COUNT(*) FROM catalog_sessions WHERE recovered=1 AND recovery_role='diverged' AND missing_since=0`).Scan(&diverged)
+	_ = c.db.QueryRowContext(ctx, `SELECT COUNT(*) FROM catalog_sessions WHERE recovered=1 AND recovery_role='covered_copy' AND missing_since=0`).Scan(&cleanup)
 	c.statusMu.Lock()
 	c.status.Indexed = indexed
 	c.status.Total = total
 	c.status.RepairPending = pending
+	c.status.PhysicalSessions = physical
+	c.status.LogicalSessions = logical
+	c.status.RecoveryGroups = groups
+	c.status.RecoveryBranches = branches
+	c.status.RecoveryDiverged = diverged
+	c.status.CleanupEligible = cleanup
 	c.status.Revision = c.revision.Load()
 	c.statusMu.Unlock()
 }
@@ -335,13 +347,16 @@ func (c *Catalog) upsertSessions(ctx context.Context, records []SessionRecord, g
 			directoryGenerations[record.Directory] = generation
 		}
 		record = classifyRecoveryLineage(record)
+		if record.LogicalTopicID == "" {
+			record.LogicalTopicID = record.TopicID
+		}
 		if _, err := tx.ExecContext(ctx, `INSERT INTO catalog_sessions(
             path,directory,scope,workspace_root,topic_id,topic_title,custom_title,
             created_at,last_activity_at,preview,turns,turns_state,recovered,
             recovery_reason,recovery_digest,parent_id,recovery_copy,recovery_group_id,
-            recovery_role,recovery_canonical,content_fingerprint,
+            recovery_role,recovery_canonical,logical_topic_id,ordinary_visible,content_fingerprint,
             meta_fingerprint,health,missing_since,seen_generation
-        ) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+        ) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)
         ON CONFLICT(path) DO UPDATE SET
             directory=excluded.directory, scope=excluded.scope,
             workspace_root=excluded.workspace_root, topic_id=excluded.topic_id,
@@ -355,6 +370,8 @@ func (c *Catalog) upsertSessions(ctx context.Context, records []SessionRecord, g
             recovery_group_id=excluded.recovery_group_id,
             recovery_role=excluded.recovery_role,
             recovery_canonical=excluded.recovery_canonical,
+            logical_topic_id=excluded.logical_topic_id,
+            ordinary_visible=excluded.ordinary_visible,
             content_fingerprint=excluded.content_fingerprint,
             meta_fingerprint=excluded.meta_fingerprint, health=excluded.health,
             missing_since=0, seen_generation=MAX(catalog_sessions.seen_generation, excluded.seen_generation)`,
@@ -364,6 +381,7 @@ func (c *Catalog) upsertSessions(ctx context.Context, records []SessionRecord, g
 			record.Recovered, record.RecoveryReason, record.RecoveryDigest,
 			record.ParentID, boolToInt(record.RecoveryCopy), record.RecoveryGroupID,
 			record.RecoveryRole, boolToInt(record.RecoveryCanonical),
+			record.LogicalTopicID, boolToInt(record.OrdinaryVisible),
 			record.ContentFingerprint, record.MetaFingerprint,
 			record.Health, 0, generation); err != nil {
 			_ = tx.Rollback()
@@ -407,7 +425,8 @@ func recomputeTopic(ctx context.Context, tx *sql.Tx, key TopicKey) error {
 	// max(sum(normal turns), max(adopted recovery turns)).
 	_, err := tx.ExecContext(ctx, `INSERT INTO catalog_topics(
         scope,workspace_root,topic_id,title,turns,turns_state,created_at,
-        last_activity_at,recovery_state,health
+        last_activity_at,recovery_state,recovery_branch_count,
+        recovery_unresolved_count,recovery_cleanup_eligible_count,health
     ) SELECT ?,?,?,
         COALESCE(NULLIF((SELECT COALESCE(NULLIF(custom_title,''), NULLIF(topic_title,''), preview, '')
             FROM catalog_sessions WHERE scope=? AND workspace_root=? AND topic_id=?
@@ -421,7 +440,14 @@ func recomputeTopic(ctx context.Context, tx *sql.Tx, key TopicKey) error {
              WHEN SUM(CASE WHEN recovery_copy=0 THEN 1 ELSE 0 END)=0 THEN 'valid'
              ELSE 'valid' END,
         COALESCE(MIN(NULLIF(created_at,0)),0), COALESCE(MAX(last_activity_at),0),
-        CASE WHEN SUM(CASE WHEN recovery_copy=0 THEN 1 ELSE 0 END)=0 THEN 'recovery_only' ELSE '' END,
+        CASE WHEN SUM(CASE WHEN recovered=1 AND recovery_role='preferred' THEN 1 ELSE 0 END)>0 THEN 'preferred'
+             WHEN SUM(CASE WHEN recovered=1 AND recovery_role='diverged' THEN 1 ELSE 0 END)>0 THEN 'diverged'
+             WHEN SUM(CASE WHEN recovered=1 AND recovery_role='adopted' THEN 1 ELSE 0 END)>0 THEN 'adopted'
+             WHEN SUM(CASE WHEN recovery_copy=0 THEN 1 ELSE 0 END)=0 THEN 'recovery_only' ELSE '' END,
+        SUM(CASE WHEN recovered=1 THEN 1 ELSE 0 END),
+        CASE WHEN SUM(CASE WHEN recovered=1 AND recovery_role='preferred' THEN 1 ELSE 0 END)>0 THEN 0
+             ELSE SUM(CASE WHEN recovered=1 AND recovery_role='diverged' THEN 1 ELSE 0 END) END,
+        SUM(CASE WHEN recovered=1 AND recovery_role='covered_copy' THEN 1 ELSE 0 END),
         CASE WHEN SUM(CASE WHEN recovery_copy=0 AND health='corrupt' THEN 1 ELSE 0 END)>0 THEN 'corrupt'
              WHEN SUM(CASE WHEN recovery_copy=0 AND health='missing' THEN 1 ELSE 0 END)>0 THEN 'missing'
              ELSE 'ok' END
@@ -429,7 +455,11 @@ func recomputeTopic(ctx context.Context, tx *sql.Tx, key TopicKey) error {
     ON CONFLICT(scope,workspace_root,topic_id) DO UPDATE SET
         title=excluded.title, turns=excluded.turns, turns_state=excluded.turns_state,
         created_at=excluded.created_at, last_activity_at=excluded.last_activity_at,
-        recovery_state=excluded.recovery_state, health=excluded.health`,
+        recovery_state=excluded.recovery_state,
+        recovery_branch_count=excluded.recovery_branch_count,
+        recovery_unresolved_count=excluded.recovery_unresolved_count,
+        recovery_cleanup_eligible_count=excluded.recovery_cleanup_eligible_count,
+        health=excluded.health`,
 		key.Scope, key.WorkspaceRoot, key.TopicID,
 		key.Scope, key.WorkspaceRoot, key.TopicID, key.TopicID,
 		key.Scope, key.WorkspaceRoot, key.TopicID)
@@ -507,48 +537,70 @@ func (c *Catalog) ListTopics(ctx context.Context, req TopicPageRequest) (TopicPa
 		}
 		pageArgs = append(pageArgs, scanLimit)
 		rows, err := c.db.QueryContext(ctx, `SELECT scope,workspace_root,topic_id,title,pinned,sort_order,
-            turns,turns_state,created_at,last_activity_at,recovery_state,health
+            turns,turns_state,created_at,last_activity_at,recovery_state,recovery_branch_count,
+            recovery_unresolved_count,recovery_cleanup_eligible_count,health
             FROM catalog_topics WHERE `+pageWhere+`
             ORDER BY pinned DESC,last_activity_at DESC,topic_id ASC LIMIT ?`, pageArgs...)
 		if err != nil {
 			return out, err
 		}
-		rawCount := 0
-		var lastScanned TopicRecord
+		// Drain the page before hydrating sessions: an open cursor holds a
+		// connection, and listTopicSessions needs a second one, so nesting them
+		// deadlocks whenever the pool is saturated (always in memory mode).
+		scanned := make([]TopicRecord, 0, scanLimit)
 		for rows.Next() {
 			var item TopicRecord
 			if err := rows.Scan(&item.Scope, &item.WorkspaceRoot, &item.TopicID, &item.Title,
 				&item.Pinned, &item.SortOrder, &item.Turns, &item.TurnsState,
-				&item.CreatedAt, &item.LastActivityAt, &item.RecoveryState, &item.Health); err != nil {
+				&item.CreatedAt, &item.LastActivityAt, &item.RecoveryState, &item.RecoveryBranchCount,
+				&item.RecoveryUnresolvedCount, &item.RecoveryCleanupEligibleCount, &item.Health); err != nil {
 				_ = rows.Close()
 				return out, err
 			}
-			rawCount++
-			lastScanned = item
-			sessions, err := c.listTopicSessions(ctx, TopicKey{
-				Scope: item.Scope, WorkspaceRoot: item.WorkspaceRoot, TopicID: item.TopicID,
-			})
-			if err != nil {
-				_ = rows.Close()
-				return TopicPage{Items: []TopicRecord{}, Revision: out.Revision}, err
-			}
-			if len(sessions) == 0 {
-				continue
-			}
-			item.Sessions = sessions
-			out.Items = append(out.Items, item)
-			if len(out.Items) > req.Limit {
-				break
-			}
+			scanned = append(scanned, item)
 		}
 		rowsErr := rows.Err()
 		_ = rows.Close()
 		if rowsErr != nil {
 			return out, rowsErr
 		}
-		if len(out.Items) > req.Limit || rawCount < scanLimit || rawCount == 0 {
+		rawCount := len(scanned)
+		overflow := false
+		for _, item := range scanned {
+			sessions, err := c.listTopicSessions(ctx, TopicKey{
+				Scope: item.Scope, WorkspaceRoot: item.WorkspaceRoot, TopicID: item.TopicID,
+			})
+			if err != nil {
+				return TopicPage{Items: []TopicRecord{}, Revision: out.Revision}, err
+			}
+			if len(sessions) == 0 {
+				continue
+			}
+			// Skip pure recovery-shell topics that lost their ordinary
+			// representative after lineage re-anchoring. Prevents empty pages
+			// and flash of conflict rows while catalog rebuilds.
+			hasOrdinary := false
+			for _, session := range sessions {
+				if session.OrdinaryVisible || (!session.Recovered && !session.RecoveryCopy) {
+					hasOrdinary = true
+					break
+				}
+			}
+			if !hasOrdinary && !item.Pinned {
+				continue
+			}
+			item.Sessions = sessions
+			item.RepresentativePath = topicRepresentativePath(sessions)
+			out.Items = append(out.Items, item)
+			if len(out.Items) > req.Limit {
+				overflow = true
+				break
+			}
+		}
+		if overflow || rawCount < scanLimit || rawCount == 0 {
 			break
 		}
+		lastScanned := scanned[rawCount-1]
 		pinned := 0
 		if lastScanned.Pinned {
 			pinned = 1
@@ -622,12 +674,14 @@ func (c *Catalog) GetTopic(ctx context.Context, key TopicKey) (TopicRecord, bool
 	key.TopicID = strings.TrimSpace(key.TopicID)
 	item := TopicRecord{Sessions: []SessionRecord{}}
 	err := c.db.QueryRowContext(ctx, `SELECT scope,workspace_root,topic_id,title,pinned,sort_order,
-        turns,turns_state,created_at,last_activity_at,recovery_state,health
+        turns,turns_state,created_at,last_activity_at,recovery_state,recovery_branch_count,
+        recovery_unresolved_count,recovery_cleanup_eligible_count,health
         FROM catalog_topics WHERE scope=? AND workspace_root=? AND topic_id=?`,
 		key.Scope, key.WorkspaceRoot, key.TopicID).Scan(
 		&item.Scope, &item.WorkspaceRoot, &item.TopicID, &item.Title,
 		&item.Pinned, &item.SortOrder, &item.Turns, &item.TurnsState,
-		&item.CreatedAt, &item.LastActivityAt, &item.RecoveryState, &item.Health)
+		&item.CreatedAt, &item.LastActivityAt, &item.RecoveryState, &item.RecoveryBranchCount,
+		&item.RecoveryUnresolvedCount, &item.RecoveryCleanupEligibleCount, &item.Health)
 	if errors.Is(err, sql.ErrNoRows) {
 		return item, false, nil
 	}
@@ -643,9 +697,38 @@ func (c *Catalog) GetTopic(ctx context.Context, key TopicKey) (TopicRecord, bool
 	if len(item.Sessions) == 0 {
 		return TopicRecord{Sessions: []SessionRecord{}}, false, nil
 	}
+	item.RepresentativePath = topicRepresentativePath(item.Sessions)
 	return item, true, nil
 }
 
+func topicRepresentativePath(sessions []SessionRecord) string {
+	if path := CanonicalSessionPathForTopic(sessions, ""); path != "" {
+		return path
+	}
+	preferred := PreferredOrdinarySessionPaths(sessions)
+	best := SessionRecord{}
+	found := false
+	for _, session := range sessions {
+		path := strings.TrimSpace(session.Path)
+		_, isPreferred := preferred[path]
+		if !session.OrdinaryVisible && !isPreferred && (session.Recovered || session.RecoveryCopy) {
+			continue
+		}
+		if !found || recoveryRank(session) > recoveryRank(best) ||
+			(recoveryRank(session) == recoveryRank(best) && session.LastActivityAt > best.LastActivityAt) {
+			best = session
+			found = true
+		}
+	}
+	if found {
+		return best.Path
+	}
+	if len(sessions) > 0 {
+		return sessions[0].Path
+	}
+	return ""
+}
+
 // EncodeTopicCursor builds an exclusive ListTopics keyset cursor after the
 // given topic position. Desktop post-filters recovery-only rows and needs the
 // same cursor shape catalog.ListTopics emits.

internal/sessioncatalog/catalog_test.go

@@ -221,7 +221,7 @@ func TestSchemaMigrationLedgerRecordsEveryVersion(t *testing.T) {
 		}
 		versions = append(versions, version)
 	}
-	if fmt.Sprint(versions) != "[1 2 3 4 5]" {
+	if fmt.Sprint(versions) != "[1 2 3 4 5 6 7]" {
 		t.Fatalf("schema migration ledger = %v", versions)
 	}
 }

internal/sessioncatalog/connection_pool_test.go

@@ -0,0 +1,177 @@
+package sessioncatalog
+
+// Guards for connection-pool starvation: every catalog API must finish on a
+// pool of one, so no path can hold a connection while waiting for another.
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"reasonix/internal/agent"
+)
+
+// A memory-mode catalog pools a single connection, so hydrating a topic's
+// sessions from inside the open topic cursor deadlocks until the caller's
+// context expires — with the desktop's boot context, forever.
+func TestListTopicsHydratesSessionsOffTheTopicCursor(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+	catalog, err := Open(ctx, Options{InMemory: true, DisableRepair: true})
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = catalog.Close(context.Background()) })
+	for _, topicID := range []string{"topic-a", "topic-b"} {
+		if err := catalog.UpsertSession(ctx, SessionRecord{
+			Path: filepath.Join("/s", topicID+".jsonl"), Directory: "/s", Scope: "global",
+			TopicID: topicID, TopicTitle: topicID, Turns: 1, TurnsState: TurnsValid,
+			Health: HealthOK, LastActivityAt: 1,
+		}); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	// A regression cannot hang the suite: it starves the pool and this deadline
+	// turns the deadlock into a failed call.
+	listCtx, cancel := context.WithTimeout(ctx, 15*time.Second)
+	defer cancel()
+	page, err := catalog.ListTopics(listCtx, TopicPageRequest{Scope: "global", Limit: MaxLimit})
+	if err != nil {
+		t.Fatalf("ListTopics on a single-connection catalog: %v", err)
+	}
+	if len(page.Items) != 2 {
+		t.Fatalf("topics = %d, want both hydrated topics", len(page.Items))
+	}
+	for _, item := range page.Items {
+		if len(item.Sessions) != 1 {
+			t.Fatalf("topic %q sessions = %d, want 1", item.TopicID, len(item.Sessions))
+		}
+	}
+}
+
+// The disk pool is four connections and every in-flight ListTopics pins one for
+// its topic cursor, so four concurrent sidebar reads used to leave the nested
+// session queries with nothing left to acquire and no deadline to break out of.
+func TestListTopicsSurvivesReadersAtThePoolLimit(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+	catalog, err := Open(ctx, Options{Path: filepath.Join(t.TempDir(), "catalog.sqlite"), DisableRepair: true})
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = catalog.Close(context.Background()) })
+	for i := range 50 {
+		topicID := fmt.Sprintf("topic-%02d", i)
+		if err := catalog.UpsertSession(ctx, SessionRecord{
+			Path: filepath.Join("/s", topicID+".jsonl"), Directory: "/s", Scope: "global",
+			TopicID: topicID, TopicTitle: topicID, Turns: 1, TurnsState: TurnsValid,
+			Health: HealthOK, LastActivityAt: int64(i + 1),
+		}); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	listCtx, cancel := context.WithTimeout(ctx, 30*time.Second)
+	defer cancel()
+	const readers = 8
+	results := make(chan error, readers)
+	for range readers {
+		go func() {
+			page, err := catalog.ListTopics(listCtx, TopicPageRequest{Scope: "global", Limit: MaxLimit})
+			if err == nil && len(page.Items) != 50 {
+				err = fmt.Errorf("topics = %d, want 50", len(page.Items))
+			}
+			results <- err
+		}()
+	}
+	for range readers {
+		if err := <-results; err != nil {
+			t.Fatalf("concurrent ListTopics: %v", err)
+		}
+	}
+}
+
+// A memory-mode catalog pools exactly one connection, so any API that holds a
+// connection while asking the pool for another deadlocks here and nowhere else
+// until production saturates a disk pool. This is the general guard: it fails
+// on the API that reintroduces the nesting, not on ListTopics specifically.
+func TestCatalogAPIsSurviveASingleConnectionPool(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+	dir := t.TempDir()
+	path := filepath.Join(dir, "session.jsonl")
+	if err := os.WriteFile(path, []byte(`{"role":"user","content":"hi"}`+"\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := agent.SaveBranchMeta(path, agent.BranchMeta{
+		Scope: "project", WorkspaceRoot: "/workspace", TopicID: "topic-1",
+		TopicTitle: "Topic", SchemaVersion: agent.BranchMetaCountsVersion, Turns: 1,
+	}); err != nil {
+		t.Fatal(err)
+	}
+	catalog, err := Open(ctx, Options{InMemory: true, DisableRepair: true})
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = catalog.Close(context.Background()) })
+	target := DirectoryTarget{Path: dir, Scope: "project", WorkspaceRoot: "/workspace"}
+	key := TopicKey{Scope: "project", WorkspaceRoot: "/workspace", TopicID: "topic-1"}
+
+	// One deadline across the whole surface: a regression surfaces as this
+	// step's error instead of a hung test binary.
+	call, cancel := context.WithTimeout(ctx, 30*time.Second)
+	defer cancel()
+	steps := []struct {
+		name string
+		run  func() error
+	}{
+		{"ReconcileDirectory", func() error { return catalog.ReconcileDirectory(call, target) }},
+		{"IndexSessionPath", func() error { return catalog.IndexSessionPath(call, target, path) }},
+		{"SyncMetadata", func() error {
+			return catalog.SyncMetadata(call,
+				[]ProjectRecord{{Scope: "project", WorkspaceRoot: "/workspace", Title: "W"}},
+				[]TopicMetadata{{Scope: "project", WorkspaceRoot: "/workspace", TopicID: "topic-1", Title: "Topic"}})
+		}},
+		{"ListTopics", func() error {
+			page, err := catalog.ListTopics(call, TopicPageRequest{Scope: "project", WorkspaceRoot: "/workspace", Limit: MaxLimit})
+			if err == nil && len(page.Items) != 1 {
+				return fmt.Errorf("topics = %d, want 1", len(page.Items))
+			}
+			return err
+		}},
+		{"GetTopic", func() error {
+			topic, ok, err := catalog.GetTopic(call, key)
+			if err == nil && (!ok || len(topic.Sessions) != 1) {
+				return fmt.Errorf("topic ok=%v sessions=%d, want one session", ok, len(topic.Sessions))
+			}
+			return err
+		}},
+		{"ListSessions", func() error {
+			page, err := catalog.ListSessions(call, SessionPageRequest{Scope: "project", WorkspaceRoot: "/workspace", Limit: MaxLimit})
+			if err == nil && len(page.Items) != 1 {
+				return fmt.Errorf("sessions = %d, want 1", len(page.Items))
+			}
+			return err
+		}},
+		{"GetSession", func() error {
+			_, ok, err := catalog.GetSession(call, path)
+			if err != nil {
+				return fmt.Errorf("get session: %w", err)
+			}
+			if !ok {
+				return fmt.Errorf("session %q missing from catalog", path)
+			}
+			return nil
+		}},
+		{"RemoveSession", func() error { return catalog.RemoveSession(call, path, "test") }},
+	}
+	for _, step := range steps {
+		if err := step.run(); err != nil {
+			t.Fatalf("%s on a single-connection catalog: %v", step.name, err)
+		}
+	}
+}

internal/sessioncatalog/lineage.go

@@ -2,7 +2,10 @@ package sessioncatalog
 
 import (
 	"context"
+	"database/sql"
+	"errors"
 	"path/filepath"
+	"sort"
 	"strings"
 
 	"reasonix/internal/agent"
@@ -52,14 +55,278 @@ func promoteCanonicalLeaves(records []SessionRecord) []SessionRecord {
 			records[i].RecoveryRole = RecoveryRoleDiverged
 			records[i].RecoveryCanonical = false
 		}
-		rootIndex, ok := groupRoot[groupID]
-		if !ok {
+		rootIndex, hasRoot := groupRoot[groupID]
+		preferred := -1
+		for _, index := range idxs {
+			if records[index].RecoveryPreferred {
+				if preferred >= 0 {
+					preferred = -2 // multiple stale preferences fail closed
+					break
+				}
+				preferred = index
+			}
+		}
+		if preferred >= 0 {
+			records[preferred].RecoveryRole = RecoveryRolePreferred
+			records[preferred].RecoveryCanonical = true
 			continue
 		}
-		candidate, ok := uniqueLongestRecovery(records, idxs)
-		if ok && recoveryCandidateCovers(records, candidate, rootIndex, idxs) {
-			records[candidate].RecoveryRole = RecoveryRoleAdopted
+		contentIdxs := append([]int{}, idxs...)
+		if hasRoot {
+			contentIdxs = append(contentIdxs, rootIndex)
+		}
+		content := loadRecoveryGroupContent(records, contentIdxs)
+		candidate, ok := uniqueLongestRecovery(records, idxs, content)
+		if !ok {
+			// No unique covering leaf: still pick one stable representative so
+			// ordinary visibility never expands into a wall of forks.
+			if len(idxs) > 0 {
+				stable := pickPreferredRecovery(indexesToRecords(records, idxs))
+				for _, i := range idxs {
+					if records[i].Path == stable.Path {
+						records[i].RecoveryCanonical = true
+						break
+					}
+				}
+			}
+			continue
+		}
+		if hasRoot && !recoveryCandidateCovers(candidate, rootIndex, idxs, content) {
 			records[candidate].RecoveryCanonical = true
+			continue
+		}
+		if !hasRoot {
+			// Root missing: the unique covering leaf is still the ordinary
+			// representative, but without a parent it cannot prove adoption.
+			records[candidate].RecoveryCanonical = true
+			for _, i := range idxs {
+				if i == candidate {
+					continue
+				}
+				if member, ok := content[i]; ok {
+					if candidateContent, ok := content[candidate]; ok && candidateContent.Covers(member) {
+						records[i].RecoveryCopy = true
+						records[i].RecoveryRole = RecoveryRoleCoveredCopy
+					}
+				}
+			}
+			continue
+		}
+		records[candidate].RecoveryRole = RecoveryRoleAdopted
+		records[candidate].RecoveryCanonical = true
+		// Once one leaf contains the entire group, every other recovery
+		// member is an ancestor/equivalent copy covered by that canonical.
+		// Marking them covered is what lets History and explicit cleanup
+		// converge an old chain instead of leaving hundreds of non-canonical
+		// "diverged" rows that preserve no unique content.
+		for _, i := range idxs {
+			if i == candidate {
+				continue
+			}
+			records[i].RecoveryCopy = true
+			records[i].RecoveryRole = RecoveryRoleCoveredCopy
+		}
+	}
+	return projectLogicalSessions(records)
+}
+
+func indexesToRecords(records []SessionRecord, idxs []int) []SessionRecord {
+	out := make([]SessionRecord, 0, len(idxs))
+	for _, i := range idxs {
+		out = append(out, records[i])
+	}
+	return out
+}
+
+// projectLogicalSessions re-anchors recovered physical files onto one logical
+// topic and marks the single ordinary-list representative. Catalog projection
+// only — authoritative JSONL/meta topic_id values are never rewritten.
+func projectLogicalSessions(records []SessionRecord) []SessionRecord {
+	byID := make(map[string]int, len(records))
+	for i := range records {
+		byID[agent.BranchID(records[i].Path)] = i
+		if !records[i].Recovered {
+			if records[i].LogicalTopicID == "" {
+				records[i].LogicalTopicID = records[i].TopicID
+			}
+			continue
+		}
+		// Filename fallback when meta ParentID is empty.
+		if strings.TrimSpace(records[i].ParentID) == "" {
+			if parent, ok := agent.RecoveryFilenameParentID(records[i].Path); ok {
+				records[i].ParentID = parent
+				if records[i].RecoveryGroupID == "" {
+					records[i].RecoveryGroupID = parent
+				}
+			}
+		}
+		if records[i].RecoveryGroupID == "" {
+			records[i].RecoveryGroupID = firstNonEmpty(records[i].ParentID, agent.BranchID(records[i].Path))
+		}
+	}
+	// Walk parent chains so intermediate recovery files also share the root id.
+	for i := range records {
+		if !records[i].Recovered {
+			continue
+		}
+		groupID := strings.TrimSpace(records[i].RecoveryGroupID)
+		seen := map[string]struct{}{}
+		parentID := strings.TrimSpace(records[i].ParentID)
+		for parentID != "" {
+			if _, loop := seen[parentID]; loop {
+				break
+			}
+			seen[parentID] = struct{}{}
+			parentIndex, ok := byID[parentID]
+			if !ok {
+				groupID = firstNonEmpty(groupID, parentID)
+				break
+			}
+			parent := records[parentIndex]
+			if !parent.Recovered {
+				groupID = parentID
+				break
+			}
+			parentID = strings.TrimSpace(parent.ParentID)
+			if parent.RecoveryGroupID != "" {
+				groupID = parent.RecoveryGroupID
+			}
+		}
+		if groupID != "" {
+			records[i].RecoveryGroupID = groupID
+		}
+	}
+
+	type groupAnchor struct {
+		topicID    string
+		topicTitle string
+		createdAt  int64
+		rootIndex  int
+	}
+	anchors := map[string]*groupAnchor{}
+	for i, rec := range records {
+		if !rec.Recovered {
+			id := agent.BranchID(rec.Path)
+			anchors[id] = &groupAnchor{
+				topicID: rec.TopicID, topicTitle: rec.TopicTitle,
+				createdAt: rec.CreatedAt, rootIndex: i,
+			}
+		}
+	}
+	// Fill missing logical topics from recovered members (root topic empty or
+	// root missing). Prefer earliest non-empty member topic_id.
+	for _, rec := range records {
+		if !rec.Recovered {
+			continue
+		}
+		groupID := strings.TrimSpace(rec.RecoveryGroupID)
+		if groupID == "" {
+			continue
+		}
+		anchor := anchors[groupID]
+		if anchor == nil {
+			anchor = &groupAnchor{rootIndex: -1, createdAt: rec.CreatedAt}
+			anchors[groupID] = anchor
+		}
+		topic := strings.TrimSpace(rec.TopicID)
+		if topic == "" {
+			continue
+		}
+		if strings.TrimSpace(anchor.topicID) == "" ||
+			(rec.CreatedAt > 0 && (anchor.createdAt == 0 || rec.CreatedAt < anchor.createdAt) &&
+				(anchor.rootIndex < 0 || strings.TrimSpace(records[anchor.rootIndex].TopicID) == "")) {
+			// Keep a non-empty root topic when present; only override empty roots.
+			if anchor.rootIndex >= 0 && strings.TrimSpace(records[anchor.rootIndex].TopicID) != "" {
+				continue
+			}
+			anchor.topicID = topic
+			anchor.topicTitle = rec.TopicTitle
+			if rec.CreatedAt > 0 {
+				anchor.createdAt = rec.CreatedAt
+			}
+		}
+	}
+	for groupID, anchor := range anchors {
+		if strings.TrimSpace(anchor.topicID) == "" {
+			// Stable internal topic so rootless recovery storms still collapse.
+			anchor.topicID = "recovery:" + groupID
+			if anchor.topicTitle == "" {
+				anchor.topicTitle = groupID
+			}
+		}
+	}
+	for i := range records {
+		groupID := ""
+		if records[i].Recovered {
+			groupID = strings.TrimSpace(records[i].RecoveryGroupID)
+		} else {
+			groupID = agent.BranchID(records[i].Path)
+		}
+		anchor := anchors[groupID]
+		if anchor == nil {
+			records[i].LogicalTopicID = firstNonEmpty(records[i].TopicID, "recovery:"+agent.BranchID(records[i].Path))
+			continue
+		}
+		records[i].LogicalTopicID = anchor.topicID
+		// Catalog ListTopics keys off TopicID. Re-anchor recovered physical
+		// rows (and roots that only inherited a member topic) onto one logical
+		// topic so pagination never materializes recovery replica walls.
+		if anchor.topicID != "" && (records[i].Recovered || strings.TrimSpace(records[i].TopicID) == "") {
+			records[i].TopicID = anchor.topicID
+		}
+		if anchor.topicTitle != "" && (records[i].Recovered || strings.TrimSpace(records[i].TopicTitle) == "") {
+			records[i].TopicTitle = anchor.topicTitle
+		}
+	}
+
+	preferred := PreferredOrdinarySessionPaths(records)
+	for i := range records {
+		_, records[i].OrdinaryVisible = preferred[strings.TrimSpace(records[i].Path)]
+		// When a group has a normal root, the root is the ordinary row even if
+		// an adopted leaf is the open target (canonical path).
+		if !records[i].Recovered {
+			records[i].OrdinaryVisible = true
+		}
+	}
+	// Exactly one ordinary-visible recovered leaf when the root is missing.
+	byGroup := map[string][]int{}
+	rootPresent := map[string]bool{}
+	for i, rec := range records {
+		if !rec.Recovered {
+			rootPresent[agent.BranchID(rec.Path)] = true
+			continue
+		}
+		if rec.RecoveryCopy || rec.RecoveryRole == RecoveryRoleCoveredCopy {
+			records[i].OrdinaryVisible = false
+			continue
+		}
+		byGroup[rec.RecoveryGroupID] = append(byGroup[rec.RecoveryGroupID], i)
+	}
+	for groupID, idxs := range byGroup {
+		if rootPresent[groupID] {
+			for _, i := range idxs {
+				records[i].OrdinaryVisible = false
+			}
+			continue
+		}
+		best := -1
+		for _, i := range idxs {
+			if records[i].RecoveryCanonical {
+				best = i
+				break
+			}
+		}
+		if best < 0 {
+			bestIdx := pickPreferredRecovery(indexesToRecords(records, idxs))
+			for _, i := range idxs {
+				if records[i].Path == bestIdx.Path {
+					best = i
+					break
+				}
+			}
+		}
+		for _, i := range idxs {
+			records[i].OrdinaryVisible = i == best
 		}
 	}
 	return records
@@ -110,39 +377,80 @@ func recoveryLineageGroups(records []SessionRecord) (map[string][]int, map[strin
 	return byGroup, groupRoot
 }
 
-func uniqueLongestRecovery(records []SessionRecord, idxs []int) (int, bool) {
+func loadRecoveryGroupContent(records []SessionRecord, idxs []int) map[int]agent.SessionContentSnapshot {
+	content := make(map[int]agent.SessionContentSnapshot, len(idxs))
+	for _, index := range idxs {
+		if _, loaded := content[index]; loaded {
+			continue
+		}
+		if snapshot, ok := agent.LoadSessionContentSnapshot(records[index].Path); ok {
+			content[index] = snapshot
+		}
+	}
+	return content
+}
+
+func uniqueLongestRecovery(records []SessionRecord, idxs []int, content map[int]agent.SessionContentSnapshot) (int, bool) {
 	if len(idxs) == 0 {
 		return 0, false
 	}
-	candidate := idxs[0]
-	if len(idxs) == 1 {
-		return candidate, true
+	// Turns/preview metadata is repaired asynchronously and must not decide
+	// lineage. Doing so made the first scan permanently label every legacy fork
+	// diverged when its sidecar still had turns_state=unknown. Instead, find the
+	// leaves that actually cover every recovered member. Equivalent leaves are
+	// safe to collapse and use a deterministic activity/path tie-breaker.
+	maxLen := -1
+	for _, index := range idxs {
+		if snapshot, ok := content[index]; ok && snapshot.Len() > maxLen {
+			maxLen = snapshot.Len()
+		}
 	}
-	if records[candidate].TurnsState == TurnsUnknown {
+	if maxLen < 0 {
 		return 0, false
 	}
-	for _, i := range idxs[1:] {
-		if records[i].TurnsState == TurnsUnknown {
-			return 0, false
+	candidates := make([]int, 0, 1)
+	for _, candidate := range idxs {
+		candidateContent, ok := content[candidate]
+		if !ok || candidateContent.Len() != maxLen {
+			continue
 		}
-		if records[i].Turns > records[candidate].Turns {
-			candidate = i
+		coversAll := true
+		for _, other := range idxs {
+			otherContent, ok := content[other]
+			if !ok || (candidate != other && !candidateContent.Covers(otherContent)) {
+				coversAll = false
+				break
+			}
+		}
+		if coversAll {
+			candidates = append(candidates, candidate)
 		}
 	}
-	for _, i := range idxs {
-		if i != candidate && records[i].Turns >= records[candidate].Turns {
-			return 0, false
-		}
+	if len(candidates) == 0 {
+		return 0, false
 	}
-	return candidate, true
+	sort.SliceStable(candidates, func(i, j int) bool {
+		a, b := records[candidates[i]], records[candidates[j]]
+		if a.LastActivityAt != b.LastActivityAt {
+			return a.LastActivityAt > b.LastActivityAt
+		}
+		return a.Path < b.Path
+	})
+	return candidates[0], true
 }
 
-func recoveryCandidateCovers(records []SessionRecord, candidate, root int, idxs []int) bool {
-	if !agent.SessionContentCovers(records[candidate].Path, records[root].Path) {
+func recoveryCandidateCovers(candidate, root int, idxs []int, content map[int]agent.SessionContentSnapshot) bool {
+	candidateContent, ok := content[candidate]
+	if !ok {
+		return false
+	}
+	rootContent, ok := content[root]
+	if !ok || !candidateContent.Covers(rootContent) {
 		return false
 	}
 	for _, i := range idxs {
-		if i != candidate && !agent.SessionContentCovers(records[candidate].Path, records[i].Path) {
+		memberContent, ok := content[i]
+		if !ok || (i != candidate && !candidateContent.Covers(memberContent)) {
 			return false
 		}
 	}
@@ -163,11 +471,20 @@ func (c *Catalog) refreshDirectoryRecoveryLineage(ctx context.Context, target Di
 	affected := map[TopicKey]struct{}{}
 	changed := false
 	for _, record := range records {
-		if !record.Recovered {
-			continue
+		// Capture the previously projected topic so re-anchored recovery rows
+		// can delete empty legacy topic shells.
+		var previous TopicKey
+		if err := tx.QueryRowContext(ctx, `SELECT scope,workspace_root,topic_id FROM catalog_sessions WHERE path=?`, record.Path).
+			Scan(&previous.Scope, &previous.WorkspaceRoot, &previous.TopicID); err == nil && previous.TopicID != "" {
+			affected[previous] = struct{}{}
+		} else if err != nil && !errors.Is(err, sql.ErrNoRows) {
+			_ = tx.Rollback()
+			return err
 		}
-		result, err := tx.ExecContext(ctx, `UPDATE catalog_sessions SET recovery_copy=?,recovery_group_id=?,recovery_role=?,recovery_canonical=? WHERE path=?`,
-			boolToInt(record.RecoveryCopy), record.RecoveryGroupID, record.RecoveryRole, boolToInt(record.RecoveryCanonical), record.Path)
+		result, err := tx.ExecContext(ctx, `UPDATE catalog_sessions SET recovered=?,recovery_copy=?,recovery_group_id=?,recovery_role=?,recovery_canonical=?,topic_id=?,topic_title=?,logical_topic_id=?,ordinary_visible=?,parent_id=? WHERE path=?`,
+			boolToInt(record.Recovered), boolToInt(record.RecoveryCopy), record.RecoveryGroupID, record.RecoveryRole,
+			boolToInt(record.RecoveryCanonical), record.TopicID, record.TopicTitle, record.LogicalTopicID,
+			boolToInt(record.OrdinaryVisible), record.ParentID, record.Path)
 		if err != nil {
 			_ = tx.Rollback()
 			return err
@@ -227,13 +544,24 @@ func firstNonEmpty(values ...string) string {
 // Empty means keep the caller's path.
 func CanonicalSessionPathForTopic(sessions []SessionRecord, current string) string {
 	var canonical string
+	canonicalRole := ""
 	for _, s := range sessions {
-		if s.RecoveryCanonical && s.RecoveryRole == RecoveryRoleAdopted {
+		if s.RecoveryCanonical && (s.RecoveryRole == RecoveryRoleAdopted || s.RecoveryRole == RecoveryRolePreferred) {
 			if canonical != "" && canonical != s.Path {
 				// Ambiguous: do not retarget.
 				return ""
 			}
 			canonical = s.Path
+			canonicalRole = s.RecoveryRole
+		}
+	}
+	if canonicalRole == RecoveryRolePreferred && current != "" {
+		for _, session := range sessions {
+			if session.Path == current && session.Recovered {
+				// An explicit click on another recovery leaf is inspection, not a
+				// request to follow the default choice.
+				return ""
+			}
 		}
 	}
 	if canonical == "" || canonical == current {

internal/sessioncatalog/lineage_test.go

@@ -2,7 +2,9 @@ package sessioncatalog
 
 import (
 	"context"
+	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 
 	"reasonix/internal/agent"
@@ -68,10 +70,41 @@ func TestPromoteCanonicalLeavesRequiresContentCoverage(t *testing.T) {
 		Path: peer, Recovered: true, ParentID: "root", RecoveryGroupID: "root", RecoveryRole: RecoveryRoleDiverged, Turns: 2, TurnsState: TurnsValid,
 	})
 	out = promoteCanonicalLeaves(recs)
+	canonical := 0
 	for _, record := range out[1:] {
-		if record.RecoveryCanonical {
-			t.Fatalf("ambiguous equal-length leaves must stay diverged: %+v", out)
+		if record.RecoveryRole != RecoveryRoleDiverged {
+			t.Fatalf("ambiguous equal-length leaves must keep diverged role: %+v", out)
 		}
+		if record.RecoveryCanonical {
+			canonical++
+		}
+	}
+	// Ordinary list still needs exactly one stable representative even when
+	// content truly forks; History remains the place to open the other leaf.
+	if canonical != 1 {
+		t.Fatalf("ambiguous group canonical count = %d, want 1 stable representative: %+v", canonical, out)
+	}
+}
+
+func TestPromoteCanonicalLeavesIgnoresUnknownTurnMetadataAndCoversAncestors(t *testing.T) {
+	dir := t.TempDir()
+	root := filepath.Join(dir, "root.jsonl")
+	ancestor := filepath.Join(dir, "ancestor.jsonl")
+	leaf := filepath.Join(dir, "leaf.jsonl")
+	saveLineageSession(t, root, "q", "a")
+	saveLineageSession(t, ancestor, "q", "a", "next", "one")
+	saveLineageSession(t, leaf, "q", "a", "next", "one", "again", "two")
+	recs := []SessionRecord{
+		{Path: root, RecoveryRole: RecoveryRoleNormal, TurnsState: TurnsUnknown},
+		{Path: ancestor, Recovered: true, ParentID: "root", RecoveryGroupID: "root", RecoveryRole: RecoveryRoleDiverged, TurnsState: TurnsUnknown},
+		{Path: leaf, Recovered: true, ParentID: "ancestor", RecoveryGroupID: "root", RecoveryRole: RecoveryRoleDiverged, TurnsState: TurnsUnknown},
+	}
+	out := promoteCanonicalLeaves(recs)
+	if !out[2].RecoveryCanonical || out[2].RecoveryRole != RecoveryRoleAdopted {
+		t.Fatalf("leaf = %+v, want adopted despite unknown turns", out[2])
+	}
+	if !out[1].RecoveryCopy || out[1].RecoveryRole != RecoveryRoleCoveredCopy {
+		t.Fatalf("ancestor = %+v, want covered copy", out[1])
 	}
 }
 
@@ -88,6 +121,31 @@ func TestCanonicalSessionPathForTopic(t *testing.T) {
 	}
 }
 
+func TestExplicitPreferredRecoveryWinsWithoutMakingPeersCovered(t *testing.T) {
+	dir := t.TempDir()
+	root := filepath.Join(dir, "root.jsonl")
+	left := filepath.Join(dir, "left.jsonl")
+	right := filepath.Join(dir, "right.jsonl")
+	saveLineageSession(t, root, "q", "a")
+	saveLineageSession(t, left, "q", "a", "left", "answer")
+	saveLineageSession(t, right, "q", "a", "right", "answer")
+	records := []SessionRecord{
+		{Path: root, RecoveryRole: RecoveryRoleNormal},
+		{Path: left, Recovered: true, ParentID: "root", RecoveryGroupID: "root", RecoveryRole: RecoveryRoleDiverged, RecoveryPreferred: true},
+		{Path: right, Recovered: true, ParentID: "root", RecoveryGroupID: "root", RecoveryRole: RecoveryRoleDiverged},
+	}
+	out := promoteCanonicalLeaves(records)
+	if !out[1].RecoveryCanonical || out[1].RecoveryRole != RecoveryRolePreferred {
+		t.Fatalf("preferred = %+v", out[1])
+	}
+	if out[2].RecoveryCopy || out[2].RecoveryRole != RecoveryRoleDiverged {
+		t.Fatalf("diverged peer must retain unique content: %+v", out[2])
+	}
+	if got := CanonicalSessionPathForTopic(out, root); got != left {
+		t.Fatalf("canonical path = %q, want %q", got, left)
+	}
+}
+
 func TestReconcilePersistsContentProvenCanonicalLeaf(t *testing.T) {
 	ctx := context.Background()
 	dir := t.TempDir()
@@ -118,3 +176,181 @@ func TestReconcilePersistsContentProvenCanonicalLeaf(t *testing.T) {
 		t.Fatalf("reconciled recovery = %+v, want adopted canonical", record)
 	}
 }
+
+func TestReconcileReanchorsCrossTopicRecoveryIntoOneLogicalTopic(t *testing.T) {
+	ctx := context.Background()
+	dir := t.TempDir()
+	root := filepath.Join(dir, "root.jsonl")
+	copyPath := filepath.Join(dir, "copy.jsonl")
+	leaf := filepath.Join(dir, "leaf.jsonl")
+	saveLineageSession(t, root, "q", "a")
+	saveLineageSession(t, copyPath, "q", "a")
+	saveLineageSession(t, leaf, "q", "a", "next", "done")
+	for path, meta := range map[string]agent.BranchMeta{
+		root:     {ID: "root", Scope: "global", TopicID: "conversation", TopicTitle: "Upgraded"},
+		copyPath: {ID: "copy", Scope: "global", TopicID: "legacy-copy-topic", Recovered: true, ParentID: "root", RecoveryDepth: 1},
+		leaf:     {ID: "leaf", Scope: "global", TopicID: "legacy-leaf-topic", Recovered: true, ParentID: "copy", RecoveryDepth: 2},
+	} {
+		if err := agent.SaveBranchMetaPreserveUpdated(path, meta); err != nil {
+			t.Fatal(err)
+		}
+	}
+	catalog, err := Open(ctx, Options{InMemory: true, DisableRepair: true})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer catalog.Close(ctx)
+	if err := catalog.ReconcileDirectory(ctx, DirectoryTarget{Path: dir, Scope: "global"}); err != nil {
+		t.Fatal(err)
+	}
+	page, err := catalog.ListTopics(ctx, TopicPageRequest{Scope: "global", Limit: 50})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(page.Items) != 1 || page.Items[0].TopicID != "conversation" {
+		t.Fatalf("ListTopics = %+v, want one logical topic conversation", page.Items)
+	}
+	leafRec, ok, err := catalog.GetSession(ctx, leaf)
+	if err != nil || !ok {
+		t.Fatalf("GetSession leaf ok=%v err=%v", ok, err)
+	}
+	if leafRec.TopicID != "conversation" || leafRec.LogicalTopicID != "conversation" {
+		t.Fatalf("leaf projection = %+v, want re-anchored to conversation", leafRec)
+	}
+	if leafRec.OrdinaryVisible {
+		t.Fatalf("leaf must not be ordinary-visible while root exists: %+v", leafRec)
+	}
+	rootRec, ok, err := catalog.GetSession(ctx, root)
+	if err != nil || !ok || !rootRec.OrdinaryVisible {
+		t.Fatalf("root ordinary visibility = %+v ok=%v err=%v", rootRec, ok, err)
+	}
+}
+
+func TestRecoveryFilenameParentID(t *testing.T) {
+	parent, ok := agent.RecoveryFilenameParentID("/s/chat-recovery-0123456789abcdef.jsonl")
+	if !ok || parent != "chat" {
+		t.Fatalf("parent = %q ok=%v", parent, ok)
+	}
+	if !agent.LooksLikeRecoveryFilename("/s/chat-recovery-0123456789abcdef.jsonl") {
+		t.Fatal("expected recovery filename")
+	}
+	if agent.LooksLikeRecoveryFilename("/s/chat.jsonl") {
+		t.Fatal("normal session must not look like recovery")
+	}
+}
+
+func TestUpgradeMatrixV4RebuildKeepsSingleLogicalRowAndAuthority(t *testing.T) {
+	// Simulates 1.24.2-style multi-topic recovery storm → new v4 projection →
+	// discard cache → reindex. Ordinary list stays one row; JSONL/meta bytes
+	// are never rewritten (the 1.23.0→new-version reinstall path).
+	ctx := context.Background()
+	dir := t.TempDir()
+	cacheDir := t.TempDir()
+	root := filepath.Join(dir, "root.jsonl")
+	copyPath := filepath.Join(dir, "copy.jsonl")
+	leaf := filepath.Join(dir, "leaf.jsonl")
+	saveLineageSession(t, root, "q", "a")
+	saveLineageSession(t, copyPath, "q", "a")
+	saveLineageSession(t, leaf, "q", "a", "next", "done")
+	for path, meta := range map[string]agent.BranchMeta{
+		root:     {ID: "root", Scope: "global", TopicID: "conversation", TopicTitle: "Upgraded"},
+		copyPath: {ID: "copy", Scope: "global", TopicID: "legacy-copy-topic", Recovered: true, ParentID: "root", RecoveryDepth: 1},
+		leaf:     {ID: "leaf", Scope: "global", TopicID: "legacy-leaf-topic", Recovered: true, ParentID: "copy", RecoveryDepth: 2},
+	} {
+		if err := agent.SaveBranchMetaPreserveUpdated(path, meta); err != nil {
+			t.Fatal(err)
+		}
+	}
+	hash := func(path string) string {
+		t.Helper()
+		data, err := os.ReadFile(path)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return string(data)
+	}
+	before := map[string]string{}
+	for _, path := range []string{root, copyPath, leaf, agent.BranchMetaPath(root), agent.BranchMetaPath(copyPath), agent.BranchMetaPath(leaf)} {
+		before[path] = hash(path)
+	}
+
+	openAndList := func(label string) (topicID, rep string) {
+		t.Helper()
+		catalog, err := Open(ctx, Options{Path: filepath.Join(cacheDir, label+".sqlite"), DisableRepair: true})
+		if err != nil {
+			t.Fatal(err)
+		}
+		defer catalog.Close(ctx)
+		if err := catalog.ReconcileDirectory(ctx, DirectoryTarget{Path: dir, Scope: "global"}); err != nil {
+			t.Fatal(err)
+		}
+		page, err := catalog.ListTopics(ctx, TopicPageRequest{Scope: "global", Limit: 50})
+		if err != nil {
+			t.Fatal(err)
+		}
+		if len(page.Items) != 1 {
+			t.Fatalf("%s ListTopics = %+v, want one logical row", label, page.Items)
+		}
+		return page.Items[0].TopicID, page.Items[0].RepresentativePath
+	}
+
+	topic1, rep1 := openAndList("pass1")
+	topic2, rep2 := openAndList("pass2")
+	if topic1 != "conversation" || topic2 != "conversation" {
+		t.Fatalf("logical topics = %q/%q, want conversation both rebuilds", topic1, topic2)
+	}
+	if rep1 == "" || rep1 != rep2 {
+		t.Fatalf("representative unstable across rebuilds: %q vs %q", rep1, rep2)
+	}
+	for path, want := range before {
+		if got := hash(path); got != want {
+			t.Fatalf("authority file mutated during catalog rebuild: %s", path)
+		}
+	}
+	// v4 path is independent of older disposable caches.
+	if !strings.HasSuffix(filepath.ToSlash(DefaultPath()), "session-catalog/v4.sqlite") && DefaultPath() != "" {
+		t.Fatalf("DefaultPath = %q, want v4.sqlite", DefaultPath())
+	}
+}
+
+func TestReconcileFoldsFilenameRecoveryIntoRootTopic(t *testing.T) {
+	ctx := context.Background()
+	dir := t.TempDir()
+	root := filepath.Join(dir, "normal.jsonl")
+	recovery := filepath.Join(dir, "normal-recovery-0123456789abcdef.jsonl")
+	saveLineageSession(t, root, "normal imported prompt")
+	saveLineageSession(t, recovery, "legacy recovery prompt")
+	if err := agent.SaveBranchMetaPreserveUpdated(root, agent.BranchMeta{
+		ID: "normal", Scope: "global", TopicID: "legacy_normal", TopicTitle: "normal",
+	}); err != nil {
+		t.Fatal(err)
+	}
+	if err := agent.SaveBranchMetaPreserveUpdated(recovery, agent.BranchMeta{
+		ID: "normal-recovery-0123456789abcdef", Scope: "global",
+		TopicID: "legacy_recovery", TopicTitle: "recovery",
+	}); err != nil {
+		t.Fatal(err)
+	}
+	catalog, err := Open(ctx, Options{InMemory: true, DisableRepair: true})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer catalog.Close(ctx)
+	if err := catalog.ReconcileDirectory(ctx, DirectoryTarget{Path: dir, Scope: "global"}); err != nil {
+		t.Fatal(err)
+	}
+	page, err := catalog.ListTopics(ctx, TopicPageRequest{Scope: "global", Limit: 50})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(page.Items) != 1 || page.Items[0].TopicID != "legacy_normal" {
+		t.Fatalf("ListTopics = %+v, want one folded legacy_normal topic", page.Items)
+	}
+	rec, ok, err := catalog.GetSession(ctx, recovery)
+	if err != nil || !ok {
+		t.Fatalf("GetSession recovery ok=%v err=%v", ok, err)
+	}
+	if !rec.Recovered || rec.TopicID != "legacy_normal" {
+		t.Fatalf("recovery projection = %+v, want re-anchored recovered row", rec)
+	}
+}

internal/sessioncatalog/ordinary_visibility.go

@@ -0,0 +1,183 @@
+package sessioncatalog
+
+import (
+	"context"
+	"path/filepath"
+	"strings"
+
+	"reasonix/internal/agent"
+)
+
+// PreferredOrdinarySessionPaths returns the session paths that may appear in
+// the ordinary project tree for one workspace. Covered recovery copies and
+// non-preferred conflict forks are omitted so the sidebar matches the 1.23
+// contract: one conversation row, not a wall of recovery replicas.
+//
+// Rules:
+//   - Every non-recovered session is preferred.
+//   - When a recovery group still has its non-recovered parent, no recovered
+//     member of that group is preferred (parent is the ordinary row).
+//   - Otherwise the group keeps a single preferred recovered leaf: canonical
+//     or adopted first, then highest turns, then latest activity.
+//
+// Open/running tabs may still force-show a path outside this set at the UI
+// boundary; this helper only encodes on-disk ordinary visibility.
+func (c *Catalog) PreferredOrdinarySessionPaths(ctx context.Context, scope, workspaceRoot string) (map[string]struct{}, error) {
+	out := map[string]struct{}{}
+	if c == nil || c.db == nil {
+		return out, nil
+	}
+	scope, workspaceRoot = normalizeScope(scope, workspaceRoot)
+	rows, err := c.db.QueryContext(ctx, `
+		SELECT path, recovered, parent_id, recovery_copy, recovery_group_id,
+		       recovery_role, recovery_canonical, turns, last_activity_at
+		FROM catalog_sessions
+		WHERE scope=? AND workspace_root=? AND missing_since=0 AND health<>'missing'`,
+		scope, workspaceRoot)
+	if err != nil {
+		return out, err
+	}
+	defer rows.Close()
+	var sessions []SessionRecord
+	for rows.Next() {
+		var rec SessionRecord
+		var recoveryCopy, recoveryCanonical, recovered int
+		if err := rows.Scan(&rec.Path, &recovered, &rec.ParentID, &recoveryCopy,
+			&rec.RecoveryGroupID, &rec.RecoveryRole, &recoveryCanonical,
+			&rec.Turns, &rec.LastActivityAt); err != nil {
+			return map[string]struct{}{}, err
+		}
+		rec.Recovered = recovered != 0
+		rec.RecoveryCopy = recoveryCopy != 0
+		rec.RecoveryCanonical = recoveryCanonical != 0
+		if rec.RecoveryRole == "" {
+			if rec.RecoveryCopy {
+				rec.RecoveryRole = RecoveryRoleCoveredCopy
+			} else if rec.Recovered {
+				rec.RecoveryRole = RecoveryRoleDiverged
+			} else {
+				rec.RecoveryRole = RecoveryRoleNormal
+			}
+		}
+		sessions = append(sessions, rec)
+	}
+	if err := rows.Err(); err != nil {
+		return map[string]struct{}{}, err
+	}
+	return PreferredOrdinarySessionPaths(sessions), nil
+}
+
+// PreferredOrdinarySessionPaths selects ordinary-tree paths from an in-memory
+// session set. Pure helper for tests and callers that already hold records.
+func PreferredOrdinarySessionPaths(sessions []SessionRecord) map[string]struct{} {
+	preferred := make(map[string]struct{}, len(sessions))
+	normalRoots := map[string]struct{}{}
+	recoveredByGroup := map[string][]SessionRecord{}
+	for _, session := range sessions {
+		path := strings.TrimSpace(session.Path)
+		if path == "" {
+			continue
+		}
+		if session.RecoveryCopy || session.RecoveryRole == RecoveryRoleCoveredCopy {
+			continue
+		}
+		if !session.Recovered {
+			preferred[path] = struct{}{}
+			normalRoots[agent.BranchID(path)] = struct{}{}
+			continue
+		}
+		key := recoveryLineageKey(session)
+		recoveredByGroup[key] = append(recoveredByGroup[key], session)
+	}
+	for group, members := range recoveredByGroup {
+		if _, parentPresent := normalRoots[group]; parentPresent {
+			// Parent conversation still exists: keep only that row.
+			continue
+		}
+		best := pickPreferredRecovery(members)
+		if path := strings.TrimSpace(best.Path); path != "" {
+			preferred[path] = struct{}{}
+		}
+	}
+	return preferred
+}
+
+// OrdinaryTreeSession reports whether a catalog session should appear in the
+// ordinary project tree given open/running runtime state and the preferred set.
+func OrdinaryTreeSession(session SessionRecord, open, running bool, preferred map[string]struct{}) bool {
+	if open || running {
+		return true
+	}
+	if session.RecoveryCopy || session.RecoveryRole == RecoveryRoleCoveredCopy {
+		return false
+	}
+	if !session.Recovered {
+		return true
+	}
+	if preferred == nil {
+		// Without a preference set, still hide covered copies (handled above)
+		// but keep recovered leaves so callers that skip preference computation
+		// do not blank the tree. Prefer building PreferredOrdinarySessionPaths.
+		return true
+	}
+	_, ok := preferred[strings.TrimSpace(session.Path)]
+	return ok
+}
+
+func recoveryLineageKey(session SessionRecord) string {
+	if group := strings.TrimSpace(session.RecoveryGroupID); group != "" {
+		return group
+	}
+	if parent := strings.TrimSpace(session.ParentID); parent != "" {
+		return parent
+	}
+	// Isolated recovered leaf without parent metadata: its own group.
+	return "path:" + agent.BranchID(session.Path)
+}
+
+func pickPreferredRecovery(members []SessionRecord) SessionRecord {
+	if len(members) == 0 {
+		return SessionRecord{}
+	}
+	best := members[0]
+	for _, candidate := range members[1:] {
+		if recoveryRank(candidate) > recoveryRank(best) {
+			best = candidate
+			continue
+		}
+		if recoveryRank(candidate) < recoveryRank(best) {
+			continue
+		}
+		if candidate.Turns != best.Turns {
+			if candidate.Turns > best.Turns {
+				best = candidate
+			}
+			continue
+		}
+		if candidate.LastActivityAt != best.LastActivityAt {
+			if candidate.LastActivityAt > best.LastActivityAt {
+				best = candidate
+			}
+			continue
+		}
+		if filepath.Base(candidate.Path) < filepath.Base(best.Path) {
+			best = candidate
+		}
+	}
+	return best
+}
+
+func recoveryRank(session SessionRecord) int {
+	switch {
+	case session.RecoveryCanonical:
+		return 3
+	case session.RecoveryRole == RecoveryRoleAdopted:
+		return 2
+	case session.RecoveryRole == RecoveryRolePreferred:
+		return 2
+	case session.RecoveryRole == RecoveryRoleDiverged || session.Recovered:
+		return 1
+	default:
+		return 0
+	}
+}

internal/sessioncatalog/ordinary_visibility_test.go

@@ -0,0 +1,100 @@
+package sessioncatalog
+
+import (
+	"context"
+	"path/filepath"
+	"testing"
+)
+
+func TestPreferredOrdinarySessionPathsHidesCoveredAndSiblingForks(t *testing.T) {
+	parent := SessionRecord{Path: "/s/root.jsonl", Recovered: false, RecoveryRole: RecoveryRoleNormal, Turns: 4}
+	covered := SessionRecord{
+		Path: "/s/root-recovery-a.jsonl", Recovered: true, RecoveryCopy: true,
+		RecoveryRole: RecoveryRoleCoveredCopy, ParentID: "root", RecoveryGroupID: "root", Turns: 2,
+	}
+	forkA := SessionRecord{
+		Path: "/s/root-recovery-b.jsonl", Recovered: true, RecoveryRole: RecoveryRoleDiverged,
+		ParentID: "root", RecoveryGroupID: "root", Turns: 5, LastActivityAt: 10,
+	}
+	forkB := SessionRecord{
+		Path: "/s/root-recovery-c.jsonl", Recovered: true, RecoveryRole: RecoveryRoleDiverged,
+		ParentID: "root", RecoveryGroupID: "root", Turns: 3, LastActivityAt: 20,
+	}
+	// Parent present → only the normal session is preferred.
+	got := PreferredOrdinarySessionPaths([]SessionRecord{parent, covered, forkA, forkB})
+	if _, ok := got[parent.Path]; !ok {
+		t.Fatalf("parent missing from preferred: %+v", got)
+	}
+	for _, path := range []string{covered.Path, forkA.Path, forkB.Path} {
+		if _, ok := got[path]; ok {
+			t.Fatalf("recovery fork %s should stay hidden while parent exists", path)
+		}
+	}
+
+	// Parent gone → keep the longest recovered leaf only.
+	got = PreferredOrdinarySessionPaths([]SessionRecord{covered, forkA, forkB})
+	if len(got) != 1 {
+		t.Fatalf("preferred = %+v, want only the longest leaf", got)
+	}
+	if _, ok := got[forkA.Path]; !ok {
+		t.Fatalf("preferred = %+v, want longest fork %s", got, forkA.Path)
+	}
+}
+
+func TestPreferredOrdinarySessionPathsPrefersCanonical(t *testing.T) {
+	short := SessionRecord{
+		Path: "/s/a.jsonl", Recovered: true, RecoveryRole: RecoveryRoleDiverged,
+		RecoveryGroupID: "g", Turns: 9, LastActivityAt: 50,
+	}
+	canonical := SessionRecord{
+		Path: "/s/b.jsonl", Recovered: true, RecoveryRole: RecoveryRoleAdopted,
+		RecoveryCanonical: true, RecoveryGroupID: "g", Turns: 2, LastActivityAt: 1,
+	}
+	got := PreferredOrdinarySessionPaths([]SessionRecord{short, canonical})
+	if _, ok := got[canonical.Path]; !ok || len(got) != 1 {
+		t.Fatalf("preferred = %+v, want canonical only", got)
+	}
+}
+
+func TestOrdinaryTreeSessionForceShowsOpenFork(t *testing.T) {
+	fork := SessionRecord{Path: "/s/fork.jsonl", Recovered: true, RecoveryRole: RecoveryRoleDiverged}
+	preferred := map[string]struct{}{}
+	if OrdinaryTreeSession(fork, false, false, preferred) {
+		t.Fatal("idle non-preferred fork must stay hidden")
+	}
+	if !OrdinaryTreeSession(fork, true, false, preferred) {
+		t.Fatal("open fork must stay reachable")
+	}
+}
+
+func TestCatalogPreferredOrdinarySessionPaths(t *testing.T) {
+	ctx := context.Background()
+	catalog, err := Open(ctx, Options{Path: filepath.Join(t.TempDir(), "c.sqlite"), DisableRepair: true})
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = catalog.Close(context.Background()) })
+	dir := t.TempDir()
+	records := []SessionRecord{
+		{Path: filepath.Join(dir, "root.jsonl"), Directory: dir, Scope: "global", TopicID: "t1",
+			Turns: 2, TurnsState: TurnsValid, Health: HealthOK, LastActivityAt: 30},
+		{Path: filepath.Join(dir, "fork.jsonl"), Directory: dir, Scope: "global", TopicID: "t2",
+			Turns: 4, TurnsState: TurnsValid, Health: HealthOK, Recovered: true,
+			ParentID: "root", RecoveryGroupID: "root", RecoveryRole: RecoveryRoleDiverged, LastActivityAt: 40},
+	}
+	for _, record := range records {
+		if err := catalog.UpsertSession(ctx, record); err != nil {
+			t.Fatal(err)
+		}
+	}
+	got, err := catalog.PreferredOrdinarySessionPaths(ctx, "global", "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, ok := got[records[0].Path]; !ok {
+		t.Fatalf("preferred = %+v, want parent", got)
+	}
+	if _, ok := got[records[1].Path]; ok {
+		t.Fatalf("preferred = %+v, parent present so fork must hide", got)
+	}
+}

internal/sessioncatalog/reconcile.go

@@ -340,6 +340,7 @@ func (c *Catalog) IndexSessionPath(ctx context.Context, target DirectoryTarget,
 		order.RecoveryReason = meta.RecoveryReason
 		order.RecoveryDigest = meta.RecoveryDigest
 		order.ParentID = meta.ParentID
+		order.RecoveryPreferred = agent.RecoveryPreferenceCurrent(path, meta)
 		order.Turns = meta.Turns
 		order.Preview = meta.Preview
 		order.SchemaVersion = meta.SchemaVersion
@@ -403,6 +404,7 @@ func recordFromOrder(target DirectoryTarget, info agent.SessionOrderInfo) Sessio
 		RecoveryReason:     info.RecoveryReason,
 		RecoveryDigest:     info.RecoveryDigest,
 		ParentID:           info.ParentID,
+		RecoveryPreferred:  info.RecoveryPreferred,
 		RecoveryCopy:       recoveryCopy,
 		ContentFingerprint: contentFingerprint,
 		MetaFingerprint:    metaFingerprint,
@@ -687,6 +689,10 @@ func (c *Catalog) applyRepairResult(ctx context.Context, path, preview string, t
 	}
 	c.publishRevision(revision, []string{key.WorkspaceRoot}, reason)
 	c.refreshCounts(ctx)
+	// Repair changes content-derived listing metadata. Reconcile the directory
+	// immediately so lineage cannot remain stuck in its pre-repair projection.
+	// Requests are coalesced and never block the repair worker.
+	c.RequestReconcile(DirectoryTarget{Path: filepath.Dir(path), Scope: key.Scope, WorkspaceRoot: key.WorkspaceRoot})
 	return nil
 }
 
@@ -793,5 +799,11 @@ func Inspect(ctx context.Context, path string) (Status, error) {
 	_ = db.QueryRowContext(ctx, `SELECT revision FROM catalog_state WHERE id=1`).Scan(&status.Revision)
 	_ = db.QueryRowContext(ctx, `SELECT COUNT(*) FROM catalog_sessions`).Scan(&status.Indexed)
 	_ = db.QueryRowContext(ctx, `SELECT COUNT(*) FROM catalog_sessions WHERE turns_state='unknown'`).Scan(&status.RepairPending)
+	_ = db.QueryRowContext(ctx, `SELECT COUNT(*) FROM catalog_sessions WHERE missing_since=0`).Scan(&status.PhysicalSessions)
+	_ = db.QueryRowContext(ctx, `SELECT COUNT(*) FROM catalog_topics`).Scan(&status.LogicalSessions)
+	_ = db.QueryRowContext(ctx, `SELECT COUNT(DISTINCT recovery_group_id) FROM catalog_sessions WHERE recovered=1 AND recovery_group_id<>'' AND missing_since=0`).Scan(&status.RecoveryGroups)
+	_ = db.QueryRowContext(ctx, `SELECT COUNT(*) FROM catalog_sessions WHERE recovered=1 AND missing_since=0`).Scan(&status.RecoveryBranches)
+	_ = db.QueryRowContext(ctx, `SELECT COUNT(*) FROM catalog_sessions WHERE recovered=1 AND recovery_role='diverged' AND missing_since=0`).Scan(&status.RecoveryDiverged)
+	_ = db.QueryRowContext(ctx, `SELECT COUNT(*) FROM catalog_sessions WHERE recovered=1 AND recovery_role='covered_copy' AND missing_since=0`).Scan(&status.CleanupEligible)
 	return status, nil
 }

internal/sessioncatalog/recovery_copy_test.go

@@ -12,15 +12,15 @@ import (
 	"reasonix/internal/provider"
 )
 
-func TestDefaultPathUsesV2CacheFile(t *testing.T) {
+func TestDefaultPathUsesV4CacheFile(t *testing.T) {
 	t.Parallel()
 	path := DefaultPath()
 	if path == "" {
 		// CacheDir unavailable in this environment; empty is still valid.
 		return
 	}
-	if !strings.HasSuffix(filepath.ToSlash(path), "session-catalog/v3.sqlite") {
-		t.Fatalf("DefaultPath = %q, want .../session-catalog/v3.sqlite", path)
+	if !strings.HasSuffix(filepath.ToSlash(path), "session-catalog/v4.sqlite") {
+		t.Fatalf("DefaultPath = %q, want .../session-catalog/v4.sqlite", path)
 	}
 	if strings.Contains(path, "v1.sqlite") {
 		t.Fatalf("DefaultPath must not reuse the 1.24.0 v1 cache: %q", path)
@@ -201,8 +201,8 @@ func TestTopicTurnsIgnoreRecoveryCopyButKeepActivity(t *testing.T) {
 	if topic.LastActivityAt != base+60_000 {
 		t.Fatalf("lastActivityAt = %d, want recovery activity", topic.LastActivityAt)
 	}
-	if topic.RecoveryState != "" {
-		t.Fatalf("recovery_state = %q, want empty for mixed topic", topic.RecoveryState)
+	if topic.RecoveryState != "recovery_only" && topic.RecoveryState != "" {
+		t.Fatalf("recovery_state = %q, want ordinary/covered-only state", topic.RecoveryState)
 	}
 }
 

internal/sessioncatalog/recovery_groups.go

@@ -0,0 +1,70 @@
+package sessioncatalog
+
+import (
+	"context"
+	"path/filepath"
+	"strings"
+)
+
+// RecoveryGroup is a catalog projection of one proved recovery lineage. It is
+// diagnostic input only; destructive callers must revalidate file contents and
+// locks through agent helpers before moving anything.
+type RecoveryGroup struct {
+	ID            string          `json:"id"`
+	Directory     string          `json:"directory"`
+	RootPath      string          `json:"rootPath,omitempty"`
+	CanonicalPath string          `json:"canonicalPath,omitempty"`
+	State         string          `json:"state"`
+	Members       []SessionRecord `json:"members"`
+}
+
+// ListRecoveryGroups returns every indexed recovery lineage in directory. All
+// slices are initialized for stable CLI/Wails JSON contracts.
+func (c *Catalog) ListRecoveryGroups(ctx context.Context, directory string) ([]RecoveryGroup, error) {
+	out := []RecoveryGroup{}
+	if c == nil || c.db == nil {
+		return out, nil
+	}
+	directory = filepath.Clean(strings.TrimSpace(directory))
+	rows, err := c.db.QueryContext(ctx, `SELECT `+sessionSelectColumns+` FROM catalog_sessions
+		WHERE directory=? AND recovered=1 AND recovery_group_id<>'' AND missing_since=0
+		ORDER BY recovery_group_id,path`, directory)
+	if err != nil {
+		return out, err
+	}
+	defer rows.Close()
+	byID := map[string]int{}
+	for rows.Next() {
+		record, err := scanSession(rows)
+		if err != nil {
+			return []RecoveryGroup{}, err
+		}
+		index, ok := byID[record.RecoveryGroupID]
+		if !ok {
+			index = len(out)
+			byID[record.RecoveryGroupID] = index
+			out = append(out, RecoveryGroup{ID: record.RecoveryGroupID, Directory: directory,
+				RootPath: filepath.Join(directory, record.RecoveryGroupID+".jsonl"), Members: []SessionRecord{}})
+		}
+		group := &out[index]
+		group.Members = append(group.Members, record)
+		if record.RecoveryCanonical && record.RecoveryRole == RecoveryRolePreferred {
+			group.CanonicalPath = record.Path
+			group.State = "preferred"
+		} else if record.RecoveryCanonical && record.RecoveryRole == RecoveryRoleAdopted {
+			group.CanonicalPath = record.Path
+			group.State = "adopted"
+		} else if group.State == "" && record.RecoveryRole == RecoveryRoleDiverged {
+			group.State = "diverged"
+		}
+	}
+	if err := rows.Err(); err != nil {
+		return []RecoveryGroup{}, err
+	}
+	for index := range out {
+		if out[index].State == "" {
+			out[index].State = "repairing"
+		}
+	}
+	return out, nil
+}

internal/sessioncatalog/schema.go

@@ -113,6 +113,19 @@ CREATE INDEX IF NOT EXISTS idx_catalog_sessions_recovery_group
 ON catalog_sessions(recovery_group_id, recovery_role, last_activity_at DESC);
 `
 
+const migrationV6 = `
+ALTER TABLE catalog_topics ADD COLUMN recovery_branch_count INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE catalog_topics ADD COLUMN recovery_unresolved_count INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE catalog_topics ADD COLUMN recovery_cleanup_eligible_count INTEGER NOT NULL DEFAULT 0;
+`
+
+const migrationV7 = `
+ALTER TABLE catalog_sessions ADD COLUMN logical_topic_id TEXT NOT NULL DEFAULT '';
+ALTER TABLE catalog_sessions ADD COLUMN ordinary_visible INTEGER NOT NULL DEFAULT 0;
+CREATE INDEX IF NOT EXISTS idx_catalog_sessions_ordinary
+ON catalog_sessions(scope, workspace_root, ordinary_visible, last_activity_at DESC);
+`
+
 func sessionMigrations() []projectiondb.Migration {
 	return []projectiondb.Migration{
 		{Version: 1, Apply: func(ctx context.Context, tx *sql.Tx) error {
@@ -135,5 +148,13 @@ func sessionMigrations() []projectiondb.Migration {
 			_, err := tx.ExecContext(ctx, migrationV5)
 			return err
 		}},
+		{Version: 6, Apply: func(ctx context.Context, tx *sql.Tx) error {
+			_, err := tx.ExecContext(ctx, migrationV6)
+			return err
+		}},
+		{Version: 7, Apply: func(ctx context.Context, tx *sql.Tx) error {
+			_, err := tx.ExecContext(ctx, migrationV7)
+			return err
+		}},
 	}
 }

internal/sessioncatalog/session_page.go

@@ -21,21 +21,25 @@ type sessionPageCursor struct {
 const sessionSelectColumns = `path,directory,scope,workspace_root,topic_id,topic_title,
     custom_title,created_at,last_activity_at,preview,turns,turns_state,recovered,
     recovery_reason,recovery_digest,parent_id,recovery_copy,recovery_group_id,
-    recovery_role,recovery_canonical,content_fingerprint,
+    recovery_role,recovery_canonical,logical_topic_id,ordinary_visible,content_fingerprint,
     meta_fingerprint,health,missing_since`
 
 func scanSession(scanner interface{ Scan(...any) error }) (SessionRecord, error) {
 	var record SessionRecord
-	var recoveryCopy, recoveryCanonical int
+	var recoveryCopy, recoveryCanonical, ordinaryVisible int
 	err := scanner.Scan(&record.Path, &record.Directory, &record.Scope, &record.WorkspaceRoot,
 		&record.TopicID, &record.TopicTitle, &record.CustomTitle, &record.CreatedAt,
 		&record.LastActivityAt, &record.Preview, &record.Turns, &record.TurnsState,
 		&record.Recovered, &record.RecoveryReason, &record.RecoveryDigest,
 		&record.ParentID, &recoveryCopy, &record.RecoveryGroupID, &record.RecoveryRole,
-		&recoveryCanonical, &record.ContentFingerprint, &record.MetaFingerprint,
+		&recoveryCanonical, &record.LogicalTopicID, &ordinaryVisible, &record.ContentFingerprint, &record.MetaFingerprint,
 		&record.Health, &record.MissingSince)
 	record.RecoveryCopy = recoveryCopy != 0
 	record.RecoveryCanonical = recoveryCanonical != 0
+	record.OrdinaryVisible = ordinaryVisible != 0
+	if record.LogicalTopicID == "" {
+		record.LogicalTopicID = record.TopicID
+	}
 	if record.RecoveryRole == "" {
 		if record.RecoveryCopy {
 			record.RecoveryRole = RecoveryRoleCoveredCopy

internal/sessioncatalog/types.go

@@ -12,7 +12,7 @@ import (
 )
 
 const (
-	SchemaVersion = 5
+	SchemaVersion = 7
 	DefaultLimit  = 50
 	MaxLimit      = 200
 )
@@ -52,15 +52,21 @@ const (
 )
 
 type Status struct {
-	State           State  `json:"state"`
-	Mode            Mode   `json:"mode"`
-	Path            string `json:"path,omitempty"`
-	Revision        uint64 `json:"revision"`
-	Indexed         int64  `json:"indexed"`
-	Total           int64  `json:"total"`
-	RepairPending   int64  `json:"repairPending"`
-	LastError       string `json:"lastError,omitempty"`
-	QuarantinedPath string `json:"quarantinedPath,omitempty"`
+	State            State  `json:"state"`
+	Mode             Mode   `json:"mode"`
+	Path             string `json:"path,omitempty"`
+	Revision         uint64 `json:"revision"`
+	Indexed          int64  `json:"indexed"`
+	Total            int64  `json:"total"`
+	RepairPending    int64  `json:"repairPending"`
+	PhysicalSessions int64  `json:"physicalSessions"`
+	LogicalSessions  int64  `json:"logicalSessions"`
+	RecoveryGroups   int64  `json:"recoveryGroups"`
+	RecoveryBranches int64  `json:"recoveryBranches"`
+	RecoveryDiverged int64  `json:"recoveryDiverged"`
+	CleanupEligible  int64  `json:"cleanupEligible"`
+	LastError        string `json:"lastError,omitempty"`
+	QuarantinedPath  string `json:"quarantinedPath,omitempty"`
 }
 
 type Options struct {
@@ -100,32 +106,40 @@ type TopicMetadata struct {
 }
 
 type SessionRecord struct {
-	Path           string     `json:"path"`
-	Directory      string     `json:"directory"`
-	Scope          string     `json:"scope"`
-	WorkspaceRoot  string     `json:"workspaceRoot,omitempty"`
-	TopicID        string     `json:"topicId,omitempty"`
-	TopicTitle     string     `json:"topicTitle,omitempty"`
-	CustomTitle    string     `json:"customTitle,omitempty"`
-	CreatedAt      int64      `json:"createdAt,omitempty"`
-	LastActivityAt int64      `json:"lastActivityAt,omitempty"`
-	Preview        string     `json:"preview,omitempty"`
-	Turns          int        `json:"turns"`
-	TurnsState     TurnsState `json:"turnsState"`
-	Recovered      bool       `json:"recovered,omitempty"`
-	RecoveryReason string     `json:"recoveryReason,omitempty"`
-	RecoveryDigest string     `json:"recoveryDigest,omitempty"`
-	ParentID       string     `json:"parentId,omitempty"`
+	Path              string     `json:"path"`
+	Directory         string     `json:"directory"`
+	Scope             string     `json:"scope"`
+	WorkspaceRoot     string     `json:"workspaceRoot,omitempty"`
+	TopicID           string     `json:"topicId,omitempty"`
+	TopicTitle        string     `json:"topicTitle,omitempty"`
+	CustomTitle       string     `json:"customTitle,omitempty"`
+	CreatedAt         int64      `json:"createdAt,omitempty"`
+	LastActivityAt    int64      `json:"lastActivityAt,omitempty"`
+	Preview           string     `json:"preview,omitempty"`
+	Turns             int        `json:"turns"`
+	TurnsState        TurnsState `json:"turnsState"`
+	Recovered         bool       `json:"recovered,omitempty"`
+	RecoveryReason    string     `json:"recoveryReason,omitempty"`
+	RecoveryDigest    string     `json:"recoveryDigest,omitempty"`
+	ParentID          string     `json:"parentId,omitempty"`
+	RecoveryPreferred bool       `json:"recoveryPreferred,omitempty"`
 	// RecoveryCopy is true only when real content is still covered by the parent.
 	RecoveryCopy bool `json:"recoveryCopy,omitempty"`
 	// RecoveryGroupID clusters a lineage of normal + recovery branches that
 	// share content ancestry. Empty for ordinary non-recovery sessions.
 	RecoveryGroupID string `json:"recoveryGroupId,omitempty"`
-	// RecoveryRole is normal | covered_copy | adopted | diverged.
+	// RecoveryRole is normal | covered_copy | adopted | preferred | diverged.
 	RecoveryRole string `json:"recoveryRole,omitempty"`
 	// RecoveryCanonical marks the unique leaf that covers the group and should
 	// be opened by default. Never moves or rewrites files.
-	RecoveryCanonical  bool   `json:"recoveryCanonical,omitempty"`
+	RecoveryCanonical bool `json:"recoveryCanonical,omitempty"`
+	// LogicalTopicID is the ordinary-list topic for this physical file. Recovery
+	// copies are re-anchored onto the root conversation's topic in the catalog
+	// only; authoritative sidecars keep their original topic_id.
+	LogicalTopicID string `json:"logicalTopicId,omitempty"`
+	// OrdinaryVisible is true only for the single logical representative that
+	// may appear in the ordinary project tree.
+	OrdinaryVisible    bool   `json:"ordinaryVisible,omitempty"`
 	ContentFingerprint string `json:"contentFingerprint,omitempty"`
 	MetaFingerprint    string `json:"metaFingerprint,omitempty"`
 	Health             Health `json:"health"`
@@ -137,6 +151,7 @@ const (
 	RecoveryRoleNormal      = "normal"
 	RecoveryRoleCoveredCopy = "covered_copy"
 	RecoveryRoleAdopted     = "adopted"
+	RecoveryRolePreferred   = "preferred"
 	RecoveryRoleDiverged    = "diverged"
 )
 
@@ -147,19 +162,24 @@ type TopicKey struct {
 }
 
 type TopicRecord struct {
-	Scope          string          `json:"scope"`
-	WorkspaceRoot  string          `json:"workspaceRoot,omitempty"`
-	TopicID        string          `json:"topicId"`
-	Title          string          `json:"title"`
-	Pinned         bool            `json:"pinned,omitempty"`
-	SortOrder      int             `json:"sortOrder,omitempty"`
-	Turns          int             `json:"turns"`
-	TurnsState     TurnsState      `json:"turnsState"`
-	CreatedAt      int64           `json:"createdAt,omitempty"`
-	LastActivityAt int64           `json:"lastActivityAt,omitempty"`
-	RecoveryState  string          `json:"recoveryState,omitempty"`
-	Health         Health          `json:"health"`
-	Sessions       []SessionRecord `json:"sessions"`
+	Scope                        string     `json:"scope"`
+	WorkspaceRoot                string     `json:"workspaceRoot,omitempty"`
+	TopicID                      string     `json:"topicId"`
+	Title                        string     `json:"title"`
+	Pinned                       bool       `json:"pinned,omitempty"`
+	SortOrder                    int        `json:"sortOrder,omitempty"`
+	Turns                        int        `json:"turns"`
+	TurnsState                   TurnsState `json:"turnsState"`
+	CreatedAt                    int64      `json:"createdAt,omitempty"`
+	LastActivityAt               int64      `json:"lastActivityAt,omitempty"`
+	RecoveryState                string     `json:"recoveryState,omitempty"`
+	RecoveryBranchCount          int        `json:"recoveryBranchCount,omitempty"`
+	RecoveryUnresolvedCount      int        `json:"recoveryUnresolvedCount,omitempty"`
+	RecoveryCleanupEligibleCount int        `json:"recoveryCleanupEligibleCount,omitempty"`
+	// RepresentativePath is the automatic open target for this logical topic.
+	RepresentativePath string          `json:"representativePath,omitempty"`
+	Health             Health          `json:"health"`
+	Sessions           []SessionRecord `json:"sessions"`
 }
 
 type TopicPageRequest struct {
@@ -195,13 +215,14 @@ type SessionPage struct {
 }
 
 // DefaultPath is the disposable cache file under CacheDir ("" when unavailable).
-// v3.sqlite is independent of the 1.24.0/1.24.1 v1/v2 caches so processes cannot
-// cross-write; polluted older catalogs are ignored and rebuilt from authoritative
-// JSONL/WAL/sidecar data.
+// v4.sqlite is independent of the v1-v3 caches so a new build never trusts a
+// polluted lineage projection produced before content-based canonical selection.
+// Session JSONL/WAL/sidecars remain authoritative and older binaries may keep
+// using their own disposable cache without cross-writing this one.
 func DefaultPath() string {
 	cache := strings.TrimSpace(config.CacheDir())
 	if cache == "" {
 		return ""
 	}
-	return filepath.Join(cache, "session-catalog", "v3.sqlite")
+	return filepath.Join(cache, "session-catalog", "v4.sqlite")
 }

internal/shellsafe/effect.go

@@ -0,0 +1,721 @@
+package shellsafe
+
+import (
+	"path/filepath"
+	"slices"
+	"strings"
+
+	"mvdan.cc/sh/v3/syntax"
+
+	"reasonix/internal/shellparse"
+)
+
+// Certainty reports whether the host could statically prove a command's
+// effects. Unknown commands fail closed at mutation and permission boundaries.
+type Certainty uint8
+
+const (
+	EffectUnknown Certainty = iota
+	EffectKnown
+)
+
+// WriteDomain identifies durable state a command can change.
+type WriteDomain uint8
+
+const (
+	WriteWorkspaceContent WriteDomain = 1 << iota
+	WriteRepositoryMetadata
+	WriteHostState
+	WriteExternalState
+)
+
+// CommandEffect is the shared, host-derived effect classification for one Bash
+// invocation. CommandFamily and Reason are deliberately argument-free so they
+// are safe to surface in policy diagnostics.
+type CommandEffect struct {
+	Certainty      Certainty
+	Writes         WriteDomain
+	PermissionSafe bool
+	ExecutesCode   bool
+	UsesNetwork    bool
+	CommandFamily  string
+	Reason         string
+}
+
+func (e CommandEffect) AnyMutation() bool { return e.Certainty != EffectKnown || e.Writes != 0 }
+func (e CommandEffect) WorkspaceMutation() bool {
+	return e.Certainty != EffectKnown || e.Writes&(WriteWorkspaceContent|WriteRepositoryMetadata) != 0
+}
+func (e CommandEffect) ContentMutation() bool {
+	return e.Certainty != EffectKnown || e.Writes&WriteWorkspaceContent != 0
+}
+func (e CommandEffect) RepositoryMutation() bool { return e.Writes&WriteRepositoryMetadata != 0 }
+func (e CommandEffect) IsPermissionReader() bool {
+	return e.Certainty == EffectKnown && e.Writes == 0 && e.PermissionSafe
+}
+
+// ClassifyBash statically classifies every top-level command segment and
+// combines their effects. It never executes expansions or helper programs.
+func ClassifyBash(command string) CommandEffect {
+	command = strings.TrimSpace(command)
+	if command == "" {
+		return unknownEffect("shell", "empty command")
+	}
+	if bashHasUnsafeLifecycle(command) {
+		return unknownEffect(commandFamilyFromSource(command), "background or process lifecycle syntax")
+	}
+	segments, _, ok := shellparse.SplitTopLevel(command)
+	if !ok || len(segments) == 0 {
+		return unknownEffect(commandFamilyFromSource(command), "unsupported shell syntax")
+	}
+
+	var aggregate CommandEffect
+	aggregate.Certainty = EffectKnown
+	aggregate.PermissionSafe = true
+	for _, segment := range segments {
+		effect := classifyBashSegment(segment)
+		aggregate.Writes |= effect.Writes
+		aggregate.ExecutesCode = aggregate.ExecutesCode || effect.ExecutesCode
+		aggregate.UsesNetwork = aggregate.UsesNetwork || effect.UsesNetwork
+		aggregate.PermissionSafe = aggregate.PermissionSafe && effect.IsPermissionReader()
+		if aggregate.CommandFamily == "" || effect.AnyMutation() || !effect.PermissionSafe {
+			aggregate.CommandFamily = effect.CommandFamily
+		}
+		if aggregate.Reason == "" && effect.Reason != "" {
+			aggregate.Reason = effect.Reason
+		}
+		if effect.Certainty != EffectKnown {
+			aggregate.Certainty = EffectUnknown
+		}
+	}
+	if aggregate.CommandFamily == "" {
+		aggregate.CommandFamily = "shell"
+	}
+	return aggregate
+}
+
+func classifyBashSegment(segment string) CommandEffect {
+	if normalized, ok := NormalizeBashSafeRedirectsForMatch(segment); ok {
+		if fields, envPrefixed, ok := staticArgv(normalized); ok {
+			return applyEnvPrefix(classifyStaticFields(fields), envPrefixed)
+		}
+		// Preserve the existing narrow, recursively proven command-substitution
+		// reader path. Its returned fields contain only opaque placeholders.
+		if base, sub, fields, ok := ClassifyReadOnlyCommand(normalized); ok {
+			effect := classifyStaticFields(fields)
+			if effect.Certainty == EffectKnown && effect.Writes == 0 {
+				effect.CommandFamily = joinFamily(base, sub)
+				return effect
+			}
+		}
+		return unknownEffect(commandFamilyFromSource(normalized), "dynamic command shape")
+	}
+
+	fields, writesFile, ok := staticFieldsWithOutputRedirect(segment)
+	if !ok {
+		return unknownEffect(commandFamilyFromSource(segment), "unsafe or unsupported redirection")
+	}
+	effect := classifyStaticFields(fields)
+	if writesFile {
+		effect.Writes |= WriteWorkspaceContent
+		effect.PermissionSafe = false
+		if effect.Reason == "" {
+			effect.Reason = "writes command output"
+		}
+	}
+	return effect
+}
+
+// staticArgv reduces one statically proven command to argv after stripping a
+// leading env wrapper. Env flags and expansions fail closed.
+func staticArgv(command string) ([]string, bool, bool) {
+	cmd, err := shellparse.ParseStaticCommand(command, shellparse.StaticCommandPolicy{
+		AllowEnvAssignments: true,
+		AllowStderrToStdout: true,
+	})
+	if err != nil || len(cmd.Argv) == 0 {
+		return nil, false, false
+	}
+	fields, envPrefixed, ok := unwrapEnvArgv(cmd.Argv)
+	if !ok {
+		return nil, envPrefixed, false
+	}
+	return fields, envPrefixed || len(cmd.Env) > 0, true
+}
+
+func unwrapEnvArgv(argv []string) ([]string, bool, bool) {
+	if len(argv) == 0 {
+		return nil, false, false
+	}
+	base := strings.ToLower(strings.TrimSuffix(filepath.Base(argv[0]), ".exe"))
+	if base != "env" {
+		return argv, false, true
+	}
+	rest := argv[1:]
+	for len(rest) > 0 {
+		tok := rest[0]
+		if strings.HasPrefix(tok, "-") {
+			return nil, true, false
+		}
+		if !strings.Contains(tok, "=") {
+			break
+		}
+		rest = rest[1:]
+	}
+	if len(rest) == 0 {
+		return nil, true, false
+	}
+	return rest, true, true
+}
+
+func applyEnvPrefix(effect CommandEffect, envPrefixed bool) CommandEffect {
+	if !envPrefixed {
+		return effect
+	}
+	effect.PermissionSafe = false
+	if effect.Reason == "" {
+		effect.Reason = "environment prefix requires permission"
+	}
+	return effect
+}
+
+// CommandArgv returns statically proven argv after stripping a leading env
+// prefix. ok is false for expansions, env flags, or unsupported syntax.
+func CommandArgv(command string) (argv []string, envPrefixed bool, ok bool) {
+	return staticArgv(strings.TrimSpace(command))
+}
+
+func classifyStaticFields(fields []string) CommandEffect {
+	if len(fields) == 0 {
+		return unknownEffect("shell", "empty command")
+	}
+	base := strings.ToLower(strings.TrimSuffix(filepath.Base(fields[0]), ".exe"))
+	args := fields[1:]
+	switch base {
+	case "git":
+		return classifyGit(args)
+	case "date":
+		return classifyDate(args)
+	case "go":
+		return classifyGo(args)
+	case "npm":
+		return classifyNPM(args)
+	case "cargo":
+		return classifyCargo(args)
+	case "test-netconnection":
+		return CommandEffect{Certainty: EffectKnown, UsesNetwork: true, CommandFamily: base, Reason: "network probe requires permission"}
+	}
+
+	if readOnlyCommands[base] {
+		effect := knownReader(base)
+		switch base {
+		case "find":
+			if hasEffectArg(args, "-exec", "-execdir", "-ok", "-okdir") {
+				return unknownCodeEffect(base, "executes a nested command")
+			}
+			if hasEffectArg(args, "-delete", "-fls", "-fprint", "-fprint0", "-fprintf") {
+				return knownWriter(base, WriteWorkspaceContent, "writes filesystem state")
+			}
+		case "sort":
+			if hasOutputArg(args) {
+				return knownWriter(base, WriteWorkspaceContent, "writes command output")
+			}
+		}
+		return effect
+	}
+	if len(args) > 0 && readOnlyPrefixes[base][strings.ToLower(args[0])] {
+		effect := knownReader(joinFamily(base, strings.ToLower(args[0])))
+		if base == "docker" || base == "kubectl" {
+			effect.UsesNetwork = true
+		}
+		return effect
+	}
+	return unknownEffect(base, "command effects are not statically known")
+}
+
+func classifyGit(args []string) CommandEffect {
+	if len(args) == 0 {
+		return unknownEffect("git", "missing git subcommand")
+	}
+	sub := strings.ToLower(args[0])
+	rest := args[1:]
+	switch sub {
+	case "branch":
+		return classifyGitBranch(rest)
+	case "tag":
+		return classifyGitTag(rest)
+	case "remote":
+		return classifyGitRemote(rest)
+	case "config":
+		return classifyGitConfig(rest)
+	case "worktree":
+		return classifyGitWorktree(rest)
+	case "stash":
+		return classifyGitStash(rest)
+	case "clean":
+		return classifyGitClean(rest)
+	case "submodule":
+		return classifyGitSubmodule(rest)
+	case "commit":
+		return classifyGitCommit(rest)
+	case "reflog":
+		if len(rest) > 0 && slices.Contains([]string{"expire", "delete", "drop"}, strings.ToLower(rest[0])) {
+			return knownWriter("git reflog", WriteRepositoryMetadata, "updates reflog metadata")
+		}
+		return knownReader("git reflog")
+	case "diff", "show", "log":
+		if hasOutputArg(rest) {
+			return knownWriter("git "+sub, WriteWorkspaceContent, "writes command output")
+		}
+		if hasEffectArg(rest, "--ext-diff", "--textconv") {
+			return unknownCodeEffect("git "+sub, "may execute an external diff helper")
+		}
+		return knownReader("git " + sub)
+	case "grep":
+		if hasArgPrefix(rest, "--open-files-in-pager") {
+			return unknownCodeEffect("git grep", "may execute an external pager")
+		}
+		return knownReader("git grep")
+	case "cat-file":
+		if hasEffectArg(rest, "--filters", "--textconv") {
+			return unknownCodeEffect("git cat-file", "may execute an external content filter")
+		}
+		return knownReader("git cat-file")
+	}
+	if readOnlyPrefixes["git"][sub] {
+		return knownReader("git " + sub)
+	}
+	return unknownEffect("git "+sub, "git subcommand effects are not statically known")
+}
+
+func classifyGitBranch(args []string) CommandEffect {
+	family := "git branch"
+	if slices.ContainsFunc(args, branchMutationArg) {
+		return knownWriter(family, WriteRepositoryMetadata, "updates branch refs or configuration")
+	}
+	listing := len(args) == 0
+	operands := 0
+	for i := 0; i < len(args); i++ {
+		arg := args[i]
+		switch {
+		case arg == "-l" || arg == "--list" || arg == "--all" || arg == "-a" || arg == "--remotes" || arg == "-r" || arg == "--show-current":
+			listing = true
+		case arg == "-v" || arg == "-vv" || arg == "--verbose" || arg == "-q" || arg == "--quiet" || arg == "-i" || arg == "--ignore-case" || arg == "--omit-empty" || arg == "--no-omit-empty":
+			listing = true
+		case branchValueOption(arg):
+			listing = true
+			if !strings.Contains(arg, "=") {
+				i++
+				if i >= len(args) {
+					return unknownEffect(family, "missing branch filter value")
+				}
+			}
+		case strings.HasPrefix(arg, "-"):
+			return unknownEffect(family, "unknown branch option")
+		default:
+			operands++
+		}
+	}
+	if operands > 0 && !hasEffectArg(args, "-l", "--list") {
+		return knownWriter(family, WriteRepositoryMetadata, "creates or resets a branch ref")
+	}
+	if listing {
+		return knownReader(family)
+	}
+	return unknownEffect(family, "ambiguous branch operation")
+}
+
+func classifyGitTag(args []string) CommandEffect {
+	family := "git tag"
+	listing := len(args) == 0
+	verify := false
+	operands := 0
+	for i := 0; i < len(args); i++ {
+		arg := args[i]
+		if tagMutationArg(arg) {
+			return knownWriter(family, WriteRepositoryMetadata, "updates tag refs")
+		}
+		switch {
+		case arg == "-l" || arg == "--list":
+			listing = true
+		case arg == "-v" || arg == "--verify":
+			verify = true
+		case arg == "-i" || arg == "--ignore-case" || strings.HasPrefix(arg, "-n") || tagFlagOption(arg):
+			listing = true
+			if tagOptionConsumesNext(arg) {
+				i++
+				if i >= len(args) {
+					return unknownEffect(family, "missing tag filter value")
+				}
+			}
+		case strings.HasPrefix(arg, "-"):
+			return unknownEffect(family, "unknown tag option")
+		default:
+			operands++
+		}
+	}
+	if verify {
+		if operands == 0 {
+			return unknownEffect(family, "missing tag verification operand")
+		}
+		effect := CommandEffect{Certainty: EffectKnown, ExecutesCode: true, CommandFamily: family, Reason: "tag verification may execute a signature helper"}
+		return effect
+	}
+	if operands > 0 && !hasEffectArg(args, "-l", "--list") {
+		return knownWriter(family, WriteRepositoryMetadata, "creates a tag ref")
+	}
+	if listing {
+		return knownReader(family)
+	}
+	return unknownEffect(family, "ambiguous tag operation")
+}
+
+func classifyGitRemote(args []string) CommandEffect {
+	family := "git remote"
+	if len(args) == 0 || allEffectArgs(args, "-v", "--verbose") {
+		return knownReader(family)
+	}
+	action := strings.ToLower(args[0])
+	if action == "get-url" {
+		return knownReader(family)
+	}
+	if slices.Contains([]string{"add", "remove", "rm", "rename", "set-url", "prune", "update"}, action) {
+		return knownWriter(family, WriteRepositoryMetadata, "updates remote configuration or refs")
+	}
+	return unknownEffect(family, "remote operation is not a proven local reader")
+}
+
+func classifyGitConfig(args []string) CommandEffect {
+	family := "git config"
+	hostScope := hasEffectArg(args, "--global", "--system")
+	for _, arg := range args {
+		name := strings.ToLower(strings.SplitN(arg, "=", 2)[0])
+		if slices.Contains([]string{"--edit", "-e"}, name) {
+			domain := WriteRepositoryMetadata
+			if hostScope {
+				domain = WriteHostState
+			}
+			return knownWriter(family, domain, "opens an editor that can write git configuration")
+		}
+		if slices.Contains([]string{"set", "unset", "unset-all", "add", "replace-all", "rename-section", "remove-section", "--unset", "--unset-all", "--add", "--replace-all", "--rename-section", "--remove-section"}, name) {
+			domain := WriteRepositoryMetadata
+			if hostScope {
+				domain = WriteHostState
+			}
+			return knownWriter(family, domain, "updates git configuration")
+		}
+	}
+	positional := 0
+	for i := 0; i < len(args); i++ {
+		arg := args[i]
+		if configOptionConsumesNext(arg) {
+			i++
+			continue
+		}
+		if strings.HasPrefix(arg, "-") || configReadAction(arg) {
+			continue
+		}
+		positional++
+	}
+	if positional <= 1 || containsConfigReadAction(args) {
+		return knownReader(family)
+	}
+	domain := WriteRepositoryMetadata
+	if hostScope {
+		domain = WriteHostState
+	}
+	return knownWriter(family, domain, "updates git configuration")
+}
+
+func classifyGitWorktree(args []string) CommandEffect {
+	family := "git worktree"
+	if len(args) > 0 && strings.EqualFold(args[0], "list") {
+		return knownReader(family)
+	}
+	if len(args) > 0 && slices.Contains([]string{"add", "remove", "move", "prune"}, strings.ToLower(args[0])) {
+		return knownWriter(family, WriteWorkspaceContent|WriteRepositoryMetadata, "updates worktrees")
+	}
+	if len(args) > 0 && slices.Contains([]string{"lock", "unlock", "repair"}, strings.ToLower(args[0])) {
+		return knownWriter(family, WriteRepositoryMetadata, "updates worktree metadata")
+	}
+	return unknownEffect(family, "worktree operation is not a proven reader")
+}
+
+func classifyGitStash(args []string) CommandEffect {
+	family := "git stash"
+	if len(args) > 0 && slices.Contains([]string{"list", "show"}, strings.ToLower(args[0])) {
+		return knownReader(family)
+	}
+	if len(args) > 0 && slices.Contains([]string{"push", "save", "pop", "apply", "drop", "clear", "branch", "store", "create"}, strings.ToLower(args[0])) {
+		return knownWriter(family, WriteWorkspaceContent|WriteRepositoryMetadata, "updates stash or working tree state")
+	}
+	return unknownEffect(family, "stash operation is not a proven reader")
+}
+
+func classifyGitClean(args []string) CommandEffect {
+	family := "git clean"
+	dryRun := false
+	force := false
+	for _, arg := range args {
+		dryRun = dryRun || arg == "--dry-run" || shortOptionContains(arg, 'n')
+		force = force || arg == "--force" || shortOptionContains(arg, 'f')
+	}
+	if dryRun && !force {
+		return knownReader(family)
+	}
+	return knownWriter(family, WriteWorkspaceContent, "removes untracked workspace content")
+}
+
+func classifyGitSubmodule(args []string) CommandEffect {
+	family := "git submodule"
+	if len(args) > 0 && slices.Contains([]string{"status", "summary"}, strings.ToLower(args[0])) {
+		return knownReader(family)
+	}
+	if len(args) > 0 && slices.Contains([]string{"add", "init", "update", "deinit", "sync", "set-url", "set-branch", "foreach", "absorbgitdirs"}, strings.ToLower(args[0])) {
+		return knownWriter(family, WriteWorkspaceContent|WriteRepositoryMetadata, "updates submodule state")
+	}
+	return unknownEffect(family, "submodule operation is not a proven reader")
+}
+
+func classifyGitCommit(args []string) CommandEffect {
+	family := "git commit"
+	pure := false
+	for i := 0; i < len(args); i++ {
+		arg := args[i]
+		switch {
+		case arg == "-q" || arg == "--quiet":
+		case arg == "-m" || arg == "--message":
+			if i+1 >= len(args) {
+				return knownWriter(family, WriteWorkspaceContent|WriteRepositoryMetadata, "ambiguous commit form")
+			}
+			pure = true
+			i++
+		case strings.HasPrefix(arg, "--message="):
+			pure = true
+		default:
+			return knownWriter(family, WriteWorkspaceContent|WriteRepositoryMetadata, "commit form may include workspace content")
+		}
+	}
+	if pure {
+		return knownWriter(family, WriteRepositoryMetadata, "creates a commit and moves refs")
+	}
+	return knownWriter(family, WriteWorkspaceContent|WriteRepositoryMetadata, "ambiguous commit form")
+}
+
+func classifyDate(args []string) CommandEffect {
+	family := "date"
+	for i := 0; i < len(args); i++ {
+		arg := args[i]
+		switch {
+		case arg == "-s" || arg == "--set" || strings.HasPrefix(arg, "--set="):
+			return knownWriter(family, WriteHostState, "sets the host clock")
+		case strings.HasPrefix(arg, "+"):
+		case slices.Contains([]string{"-u", "--utc", "--universal", "-R", "--rfc-email", "--resolution", "--debug", "-j"}, arg):
+		case strings.HasPrefix(arg, "--iso-8601") || strings.HasPrefix(arg, "--rfc-3339"):
+		case slices.Contains([]string{"-d", "--date", "-r", "--reference", "-f", "--file"}, arg):
+			i++
+			if i >= len(args) {
+				return unknownEffect(family, "missing date reader value")
+			}
+		case strings.HasPrefix(arg, "--date=") || strings.HasPrefix(arg, "--reference=") || strings.HasPrefix(arg, "--file="):
+		case strings.HasPrefix(arg, "-"):
+			return unknownEffect(family, "unknown date option")
+		default:
+			return knownWriter(family, WriteHostState, "may set the host clock")
+		}
+	}
+	return knownReader(family)
+}
+
+func classifyGo(args []string) CommandEffect {
+	if len(args) == 0 {
+		return unknownEffect("go", "missing go subcommand")
+	}
+	sub := strings.ToLower(args[0])
+	rest := args[1:]
+	family := "go " + sub
+	if sub == "env" && hasEffectArg(rest, "-w", "-u") {
+		return knownWriter(family, WriteHostState, "updates Go environment configuration")
+	}
+	if sub == "list" {
+		for i, arg := range rest {
+			if arg == "-modfile" || strings.HasPrefix(arg, "-modfile=") || arg == "-mod=mod" || (arg == "-mod" && i+1 < len(rest) && rest[i+1] == "mod") {
+				return knownWriter(family, WriteWorkspaceContent, "may update module files")
+			}
+		}
+	}
+	if readOnlyPrefixes["go"][sub] {
+		return knownReader(family)
+	}
+	return unknownEffect(family, "go subcommand effects are not statically known")
+}
+
+func classifyNPM(args []string) CommandEffect {
+	if len(args) == 0 {
+		return unknownEffect("npm", "missing npm subcommand")
+	}
+	sub := strings.ToLower(args[0])
+	family := "npm " + sub
+	if sub == "audit" {
+		effect := knownReader(family)
+		effect.UsesNetwork = true
+		if hasEffectArg(args[1:], "fix", "--fix") {
+			effect.Writes = WriteWorkspaceContent
+			effect.PermissionSafe = false
+			effect.Reason = "updates dependency manifests or lockfiles"
+		}
+		return effect
+	}
+	if readOnlyPrefixes["npm"][sub] {
+		effect := knownReader(family)
+		effect.UsesNetwork = sub == "view" || sub == "info" || sub == "outdated"
+		return effect
+	}
+	return unknownEffect(family, "npm subcommand effects are not statically known")
+}
+
+func classifyCargo(args []string) CommandEffect {
+	if len(args) == 0 {
+		return unknownEffect("cargo", "missing cargo subcommand")
+	}
+	sub := strings.ToLower(args[0])
+	family := "cargo " + sub
+	if sub == "check" || sub == "doc" {
+		effect := knownWriter(family, WriteWorkspaceContent, "writes build artifacts and may run build scripts")
+		effect.ExecutesCode = true
+		return effect
+	}
+	if sub == "search" {
+		effect := knownReader(family)
+		effect.UsesNetwork = true
+		return effect
+	}
+	return unknownEffect(family, "cargo subcommand effects are not statically known")
+}
+
+func knownReader(family string) CommandEffect {
+	return CommandEffect{Certainty: EffectKnown, PermissionSafe: true, CommandFamily: family}
+}
+func knownWriter(family string, writes WriteDomain, reason string) CommandEffect {
+	return CommandEffect{Certainty: EffectKnown, Writes: writes, CommandFamily: family, Reason: reason}
+}
+func unknownEffect(family, reason string) CommandEffect {
+	return CommandEffect{Certainty: EffectUnknown, CommandFamily: strings.TrimSpace(family), Reason: reason}
+}
+
+func unknownCodeEffect(family, reason string) CommandEffect {
+	effect := unknownEffect(family, reason)
+	effect.ExecutesCode = true
+	return effect
+}
+
+func joinFamily(base, sub string) string {
+	if sub == "" {
+		return base
+	}
+	return base + " " + sub
+}
+
+func commandFamilyFromSource(command string) string {
+	features, ok := shellparse.AnalyzeApprovalFeatures(command)
+	if !ok || len(features.CommandPrefix) == 0 {
+		return "shell"
+	}
+	base := strings.ToLower(strings.TrimSuffix(filepath.Base(features.CommandPrefix[0]), ".exe"))
+	if len(features.CommandPrefix) > 1 && slices.Contains([]string{"git", "go", "npm", "cargo", "docker", "kubectl"}, base) {
+		return joinFamily(base, strings.ToLower(features.CommandPrefix[1]))
+	}
+	return base
+}
+
+func bashHasUnsafeLifecycle(command string) bool {
+	file, err := shellparse.ParseBash(command)
+	if err != nil {
+		return false
+	}
+	unsafe := false
+	syntax.Walk(file, func(node syntax.Node) bool {
+		stmt, ok := node.(*syntax.Stmt)
+		if ok && (stmt.Background || stmt.Coprocess || stmt.Disown) {
+			unsafe = true
+			return false
+		}
+		return !unsafe
+	})
+	return unsafe
+}
+
+func staticFieldsWithOutputRedirect(command string) ([]string, bool, bool) {
+	file, err := shellparse.ParseBash(command)
+	if err != nil || shellparse.HasHereDoc(file) || len(file.Stmts) != 1 {
+		return nil, false, false
+	}
+	stmt := file.Stmts[0]
+	call, ok := stmt.Cmd.(*syntax.CallExpr)
+	if !ok || len(call.Assigns) > 0 || stmt.Background || stmt.Negated || stmt.Coprocess || stmt.Disown {
+		return nil, false, false
+	}
+	fields := make([]string, 0, len(call.Args))
+	for _, word := range call.Args {
+		field, static := shellparse.StaticWord(word)
+		if !static {
+			return nil, false, false
+		}
+		fields = append(fields, field)
+	}
+	writes := false
+	for _, redirect := range stmt.Redirs {
+		switch redirect.Op {
+		case syntax.RdrOut, syntax.AppOut, syntax.RdrClob, syntax.AppClob, syntax.RdrAll, syntax.AppAll, syntax.RdrAllClob, syntax.AppAllClob:
+			writes = true
+		default:
+			return nil, false, false
+		}
+	}
+	return fields, writes, len(fields) > 0
+}
+
+func branchMutationArg(arg string) bool {
+	return slices.Contains([]string{"-d", "-D", "--delete", "--no-delete", "-m", "-M", "--move", "--no-move", "-c", "-C", "--copy", "--no-copy", "-f", "--force", "--no-force", "-t", "--track", "--no-track", "-u", "--set-upstream-to", "--unset-upstream", "--edit-description", "--create-reflog", "--recurse-submodules"}, strings.SplitN(arg, "=", 2)[0])
+}
+func branchValueOption(arg string) bool {
+	return slices.Contains([]string{"--contains", "--no-contains", "--merged", "--no-merged", "--points-at", "--sort", "--format", "--color", "--column", "--abbrev"}, strings.SplitN(arg, "=", 2)[0])
+}
+func tagMutationArg(arg string) bool {
+	return slices.Contains([]string{"-d", "--delete", "-a", "--annotate", "-s", "--sign", "-u", "--local-user", "-f", "--force", "-m", "--message", "-F", "--file", "-e", "--edit", "--trailer", "--cleanup", "--create-reflog"}, strings.SplitN(arg, "=", 2)[0])
+}
+func tagFlagOption(arg string) bool {
+	return slices.Contains([]string{"--contains", "--no-contains", "--merged", "--no-merged", "--points-at", "--sort", "--format", "--column", "--no-column", "--color", "--no-color", "--omit-empty", "--no-omit-empty"}, strings.SplitN(arg, "=", 2)[0])
+}
+
+func tagOptionConsumesNext(arg string) bool {
+	return !strings.Contains(arg, "=") && slices.Contains([]string{"--contains", "--no-contains", "--merged", "--no-merged", "--points-at", "--sort", "--format"}, arg)
+}
+
+func configReadAction(arg string) bool {
+	return slices.Contains([]string{"get", "get-all", "get-regexp", "get-urlmatch", "list", "--get", "--get-all", "--get-regexp", "--get-urlmatch", "--list", "--get-color", "--get-colorbool"}, strings.ToLower(arg))
+}
+
+func containsConfigReadAction(args []string) bool { return slices.ContainsFunc(args, configReadAction) }
+func configOptionConsumesNext(arg string) bool {
+	return slices.Contains([]string{"--file", "-f", "--blob", "--type", "--default", "--fixed-value"}, strings.ToLower(arg))
+}
+
+func hasEffectArg(args []string, candidates ...string) bool {
+	return slices.ContainsFunc(args, func(arg string) bool {
+		return slices.Contains(candidates, strings.SplitN(arg, "=", 2)[0])
+	})
+}
+
+func hasArgPrefix(args []string, prefix string) bool {
+	return slices.ContainsFunc(args, func(arg string) bool { return strings.HasPrefix(arg, prefix) })
+}
+func allEffectArgs(args []string, allowed ...string) bool {
+	return len(args) > 0 && !slices.ContainsFunc(args, func(arg string) bool { return !slices.Contains(allowed, arg) })
+}
+func hasOutputArg(args []string) bool {
+	return hasEffectArg(args, "-o", "--output") || hasArgPrefix(args, "-o")
+}
+func shortOptionContains(arg string, flag byte) bool {
+	return len(arg) > 1 && arg[0] == '-' && arg[1] != '-' && strings.ContainsRune(arg[1:], rune(flag))
+}

internal/shellsafe/effect_test.go

@@ -0,0 +1,158 @@
+package shellsafe
+
+import (
+	"encoding/json"
+	"os"
+	"testing"
+)
+
+type sharedEffectCase struct {
+	Name, Command                                    string
+	Certainty                                        string
+	Writes                                           []string
+	PermissionReader, ExecutesCode, UsesNetwork      bool
+	TaskPolicyBlocked, ContentMutation, BatchBarrier bool
+}
+
+func loadSharedEffectCases(t *testing.T, path string) []sharedEffectCase {
+	t.Helper()
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var cases []sharedEffectCase
+	if err := json.Unmarshal(raw, &cases); err != nil {
+		t.Fatal(err)
+	}
+	return cases
+}
+
+func TestSharedCommandEffectMatrix(t *testing.T) {
+	for _, tc := range loadSharedEffectCases(t, "testdata/command_effects.json") {
+		t.Run(tc.Name, func(t *testing.T) {
+			got := ClassifyBash(tc.Command)
+			wantCertainty := EffectKnown
+			if tc.Certainty == "unknown" {
+				wantCertainty = EffectUnknown
+			}
+			var wantWrites WriteDomain
+			for _, domain := range tc.Writes {
+				switch domain {
+				case "content":
+					wantWrites |= WriteWorkspaceContent
+				case "repository":
+					wantWrites |= WriteRepositoryMetadata
+				case "host":
+					wantWrites |= WriteHostState
+				case "external":
+					wantWrites |= WriteExternalState
+				}
+			}
+			if got.Certainty != wantCertainty || got.Writes != wantWrites || got.IsPermissionReader() != tc.PermissionReader ||
+				got.ExecutesCode != tc.ExecutesCode || got.UsesNetwork != tc.UsesNetwork || got.ContentMutation() != tc.ContentMutation {
+				t.Fatalf("ClassifyBash(%q) = %+v, matrix=%+v", tc.Command, got, tc)
+			}
+		})
+	}
+}
+
+func TestClassifyBashCommandEffects(t *testing.T) {
+	tests := []struct {
+		name       string
+		command    string
+		certainty  Certainty
+		writes     WriteDomain
+		permission bool
+		executes   bool
+		network    bool
+		family     string
+	}{
+		{name: "branch all", command: "git branch -a", certainty: EffectKnown, permission: true, family: "git branch"},
+		{name: "branch remotes", command: "git branch --remotes", certainty: EffectKnown, permission: true, family: "git branch"},
+		{name: "branch filtered list", command: "git branch --list 'release/*'", certainty: EffectKnown, permission: true, family: "git branch"},
+		{name: "branch show current", command: "git branch --show-current", certainty: EffectKnown, permission: true, family: "git branch"},
+		{name: "branch create", command: "git branch feature/new", certainty: EffectKnown, writes: WriteRepositoryMetadata, family: "git branch"},
+		{name: "branch delete", command: "git branch -D feature/old", certainty: EffectKnown, writes: WriteRepositoryMetadata, family: "git branch"},
+		{name: "branch upstream", command: "git branch --set-upstream-to origin/main", certainty: EffectKnown, writes: WriteRepositoryMetadata, family: "git branch"},
+
+		{name: "tag list", command: "git tag --list 'v1.*'", certainty: EffectKnown, permission: true, family: "git tag"},
+		{name: "tag create", command: "git tag v1.2.3", certainty: EffectKnown, writes: WriteRepositoryMetadata, family: "git tag"},
+		{name: "tag delete", command: "git tag -d v1.2.3", certainty: EffectKnown, writes: WriteRepositoryMetadata, family: "git tag"},
+
+		{name: "remote list", command: "git remote -v", certainty: EffectKnown, permission: true, family: "git remote"},
+		{name: "remote get url", command: "git remote get-url origin", certainty: EffectKnown, permission: true, family: "git remote"},
+		{name: "remote add", command: "git remote add origin example.invalid/repo", certainty: EffectKnown, writes: WriteRepositoryMetadata, family: "git remote"},
+
+		{name: "config list", command: "git config --list", certainty: EffectKnown, permission: true, family: "git config"},
+		{name: "config get", command: "git config --get user.name", certainty: EffectKnown, permission: true, family: "git config"},
+		{name: "config legacy get", command: "git config user.name", certainty: EffectKnown, permission: true, family: "git config"},
+		{name: "config local set", command: "git config user.name example", certainty: EffectKnown, writes: WriteRepositoryMetadata, family: "git config"},
+		{name: "config global set", command: "git config --global user.name example", certainty: EffectKnown, writes: WriteHostState, family: "git config"},
+		{name: "config edit", command: "git config --edit", certainty: EffectKnown, writes: WriteRepositoryMetadata, family: "git config"},
+		{name: "config global edit", command: "git config --global -e", certainty: EffectKnown, writes: WriteHostState, family: "git config"},
+		{name: "env prefixed status", command: "GOROOT=/x git status", certainty: EffectKnown, family: "git status"},
+		{name: "env utility status", command: "env GOROOT=/x git status", certainty: EffectKnown, family: "git status"},
+		{name: "env flags fail closed", command: "env -i git status", certainty: EffectUnknown, family: "env"},
+
+		{name: "worktree list", command: "git worktree list", certainty: EffectKnown, permission: true, family: "git worktree"},
+		{name: "worktree add", command: "git worktree add ../wt feature", certainty: EffectKnown, writes: WriteWorkspaceContent | WriteRepositoryMetadata, family: "git worktree"},
+		{name: "stash list", command: "git stash list", certainty: EffectKnown, permission: true, family: "git stash"},
+		{name: "stash show", command: "git stash show -p", certainty: EffectKnown, permission: true, family: "git stash"},
+		{name: "stash pop", command: "git stash pop", certainty: EffectKnown, writes: WriteWorkspaceContent | WriteRepositoryMetadata, family: "git stash"},
+		{name: "clean dry run", command: "git clean -ndx", certainty: EffectKnown, permission: true, family: "git clean"},
+		{name: "clean force", command: "git clean -fd", certainty: EffectKnown, writes: WriteWorkspaceContent, family: "git clean"},
+		{name: "submodule status", command: "git submodule status", certainty: EffectKnown, permission: true, family: "git submodule"},
+		{name: "submodule update", command: "git submodule update --init", certainty: EffectKnown, writes: WriteWorkspaceContent | WriteRepositoryMetadata, family: "git submodule"},
+
+		{name: "pure commit", command: "git commit -q -m 'checkpoint'", certainty: EffectKnown, writes: WriteRepositoryMetadata, family: "git commit"},
+		{name: "commit all", command: "git commit -am 'checkpoint'", certainty: EffectKnown, writes: WriteWorkspaceContent | WriteRepositoryMetadata, family: "git commit"},
+		{name: "commit amend", command: "git commit --amend -m 'checkpoint'", certainty: EffectKnown, writes: WriteWorkspaceContent | WriteRepositoryMetadata, family: "git commit"},
+
+		{name: "diff reader", command: "git diff --check", certainty: EffectKnown, permission: true, family: "git diff"},
+		{name: "diff output", command: "git diff --output=changes.patch", certainty: EffectKnown, writes: WriteWorkspaceContent, family: "git diff"},
+		{name: "diff external helper", command: "git diff --ext-diff", certainty: EffectUnknown, executes: true, family: "git diff"},
+		{name: "grep pager", command: "git grep --open-files-in-pager=vim needle", certainty: EffectUnknown, executes: true, family: "git grep"},
+
+		{name: "date display", command: "date -u +%s", certainty: EffectKnown, permission: true, family: "date"},
+		{name: "date set GNU", command: "date --set tomorrow", certainty: EffectKnown, writes: WriteHostState, family: "date"},
+		{name: "date set BSD", command: "date 081122302026", certainty: EffectKnown, writes: WriteHostState, family: "date"},
+		{name: "npm audit", command: "npm audit", certainty: EffectKnown, permission: true, network: true, family: "npm audit"},
+		{name: "npm audit fix", command: "npm audit fix", certainty: EffectKnown, writes: WriteWorkspaceContent, network: true, family: "npm audit"},
+		{name: "go list", command: "go list ./...", certainty: EffectKnown, permission: true, family: "go list"},
+		{name: "go list readonly modules", command: "go list -mod=readonly ./...", certainty: EffectKnown, permission: true, family: "go list"},
+		{name: "go list module update", command: "go list -mod=mod ./...", certainty: EffectKnown, writes: WriteWorkspaceContent, family: "go list"},
+		{name: "cargo check", command: "cargo check", certainty: EffectKnown, writes: WriteWorkspaceContent, executes: true, family: "cargo check"},
+
+		{name: "safe pipeline", command: "git branch -a | head -10", certainty: EffectKnown, permission: true, family: "git branch"},
+		{name: "safe fd redirect", command: "git branch -a 2>&1", certainty: EffectKnown, permission: true, family: "git branch"},
+		{name: "file redirect", command: "git status > status.txt", certainty: EffectKnown, writes: WriteWorkspaceContent, family: "git status"},
+		{name: "reader then writer", command: "git status && git branch -D old", certainty: EffectKnown, writes: WriteRepositoryMetadata, family: "git branch"},
+		{name: "dynamic expansion", command: "echo $HOME", certainty: EffectUnknown, family: "echo"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := ClassifyBash(tt.command)
+			if got.Certainty != tt.certainty || got.Writes != tt.writes || got.PermissionSafe != tt.permission ||
+				got.ExecutesCode != tt.executes || got.UsesNetwork != tt.network || got.CommandFamily != tt.family {
+				t.Fatalf("ClassifyBash(%q) = %+v, want certainty=%v writes=%v permission=%t executes=%t network=%t family=%q",
+					tt.command, got, tt.certainty, tt.writes, tt.permission, tt.executes, tt.network, tt.family)
+			}
+		})
+	}
+}
+
+func TestCommandEffectProjectionsFailClosed(t *testing.T) {
+	unknown := CommandEffect{Certainty: EffectUnknown}
+	if !unknown.AnyMutation() || !unknown.WorkspaceMutation() || !unknown.ContentMutation() {
+		t.Fatalf("unknown projections must fail closed: %+v", unknown)
+	}
+	if unknown.RepositoryMutation() || unknown.IsPermissionReader() {
+		t.Fatalf("unknown effect must not invent a repository classification or permission trust: %+v", unknown)
+	}
+
+	repo := CommandEffect{Certainty: EffectKnown, Writes: WriteRepositoryMetadata}
+	if !repo.AnyMutation() || !repo.WorkspaceMutation() || repo.ContentMutation() || !repo.RepositoryMutation() {
+		t.Fatalf("repository-only projections are inconsistent: %+v", repo)
+	}
+}

internal/shellsafe/shellsafe.go

@@ -12,11 +12,11 @@ import (
 	"reasonix/internal/shellparse"
 )
 
-// ReadOnlyCommands holds single-word commands whose base name alone implies a
+// readOnlyCommands holds single-word commands whose base name alone implies a
 // read-only operation. The first word of a command (lowercased) is looked up
 // here. Commands that are read-only only for certain subcommands (e.g. git) are
-// in ReadOnlyPrefixes.
-var ReadOnlyCommands = map[string]bool{
+// in readOnlyPrefixes.
+var readOnlyCommands = map[string]bool{
 	"cat": true, "head": true, "tail": true, "less": true, "more": true,
 	"ls": true, "find": true, "locate": true, "which": true, "whereis": true, "type": true,
 	"grep": true, "egrep": true, "fgrep": true, "rg": true,
@@ -42,18 +42,18 @@ var ReadOnlyCommands = map[string]bool{
 
 // workspaceNonMutatingCommands holds commands that do not write workspace
 // state but are not safe to auto-allow as permission-layer readers. Keep this
-// separate from ReadOnlyCommands: Test-NetConnection performs network I/O and
+// separate from readOnlyCommands: Test-NetConnection performs network I/O and
 // must still pass through the user's permission policy even though Delivery
 // does not need to serialize it behind the workspace writer.
 var workspaceNonMutatingCommands = map[string]bool{
 	"test-netconnection": true,
 }
 
-// ReadOnlyPrefixes maps a base command to the set of subcommands (the second
+// readOnlyPrefixes maps a base command to the set of subcommands (the second
 // word) that are read-only. A subcommand not listed here is treated as not
 // read-only (fail-closed): write-capable subcommands (git branch/remote/config,
 // go build/test, npm install, …) are deliberately absent.
-var ReadOnlyPrefixes = map[string]map[string]bool{
+var readOnlyPrefixes = map[string]map[string]bool{
 	"git": {
 		"log": true, "status": true, "diff": true, "show": true,
 		"tag":   true,
@@ -94,11 +94,8 @@ func ContainsShellSyntax(cmd string) bool {
 	return shellparse.ContainsShellSyntax(cmd)
 }
 
-// CommandIsReadOnly reports whether the command's base/subcommand is in the
-// read-only tables, ignoring argument rigor (which each consumer applies). It
-// returns the base and subcommand so callers can run their own arg checks.
-// ok is false when the command contains shell syntax or the base/subcommand is
-// not a known read-only operation.
+// CommandIsReadOnly is the legacy coarse read-only adapter.
+// Deprecated: production policy must use ClassifyBash and project its axis.
 func CommandIsReadOnly(command string) (base, sub string, ok bool) {
 	base, sub, _, ok = ClassifyReadOnlyCommand(command)
 	return base, sub, ok
@@ -107,6 +104,7 @@ func CommandIsReadOnly(command string) (base, sub string, ok bool) {
 // ClassifyReadOnlyCommand returns the resolved argument fields as well as the
 // command classification. Dynamic fields are opaque placeholders and are
 // returned only for the narrowly verified substitution shape above.
+// Deprecated: retained for compatibility and narrow substitution validation.
 func ClassifyReadOnlyCommand(command string) (base, sub string, fields []string, ok bool) {
 	fields, malformed := shellparse.StaticFields(command)
 	if malformed != "" {
@@ -120,14 +118,14 @@ func ClassifyReadOnlyCommand(command string) (base, sub string, fields []string,
 		return "", "", nil, false
 	}
 	base = strings.ToLower(fields[0])
-	if ReadOnlyCommands[base] {
+	if readOnlyCommands[base] {
 		if hasResolvedSubstitution(fields) && !substitutionSafeCommands[base] {
 			return "", "", nil, false
 		}
 		return base, "", fields, true
 	}
 	if len(fields) > 1 {
-		if subs, prefixed := ReadOnlyPrefixes[base]; prefixed {
+		if subs, prefixed := readOnlyPrefixes[base]; prefixed {
 			sub = strings.ToLower(fields[1])
 			if subs[sub] {
 				return base, sub, fields, true
@@ -254,12 +252,12 @@ func readOnlyFields(fields []string) (base, sub string, ok bool) {
 		return "", "", false
 	}
 	base = strings.ToLower(fields[0])
-	if ReadOnlyCommands[base] {
+	if readOnlyCommands[base] {
 		return base, "", true
 	}
 	if len(fields) > 1 {
 		sub = strings.ToLower(fields[1])
-		if ReadOnlyPrefixes[base][sub] {
+		if readOnlyPrefixes[base][sub] {
 			return base, sub, true
 		}
 	}
@@ -292,6 +290,7 @@ func nestedReadOnlyArgsSafe(base, sub string, fields []string) bool {
 // without acquiring the workspace writer. Permission-safe readers are a
 // subset; network probes live only in workspaceNonMutatingCommands so this
 // classification cannot silently widen approval or read-only subagent access.
+// Deprecated: production policy consumers must use ClassifyBash.
 func CommandIsWorkspaceNonMutating(command string) (base, sub string, ok bool) {
 	base, sub, _, ok = ClassifyWorkspaceNonMutatingCommand(command)
 	return base, sub, ok
@@ -299,6 +298,7 @@ func CommandIsWorkspaceNonMutating(command string) (base, sub string, ok bool) {
 
 // ClassifyWorkspaceNonMutatingCommand is the field-carrying form used by
 // Delivery mutation accounting.
+// Deprecated: retained as a compatibility adapter.
 func ClassifyWorkspaceNonMutatingCommand(command string) (base, sub string, fields []string, ok bool) {
 	if base, sub, fields, ok = ClassifyReadOnlyCommand(command); ok {
 		return base, sub, fields, true

internal/shellsafe/testdata/command_effects.json

@@ -0,0 +1,40 @@
+[
+  {"name":"branch list","command":"git branch -a","certainty":"known","writes":[],"permissionReader":true,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":false,"contentMutation":false,"batchBarrier":false},
+  {"name":"branch delete","command":"git branch -D private-operand","certainty":"known","writes":["repository"],"permissionReader":false,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":true,"contentMutation":false,"batchBarrier":true},
+  {"name":"tag list","command":"git tag --list 'v1.*'","certainty":"known","writes":[],"permissionReader":true,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":false,"contentMutation":false,"batchBarrier":false},
+  {"name":"tag create","command":"git tag private-operand","certainty":"known","writes":["repository"],"permissionReader":false,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":true,"contentMutation":false,"batchBarrier":true},
+  {"name":"remote list","command":"git remote -v","certainty":"known","writes":[],"permissionReader":true,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":false,"contentMutation":false,"batchBarrier":false},
+  {"name":"config list","command":"git config --list","certainty":"known","writes":[],"permissionReader":true,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":false,"contentMutation":false,"batchBarrier":false},
+  {"name":"config set","command":"git config user.name private-operand","certainty":"known","writes":["repository"],"permissionReader":false,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":true,"contentMutation":false,"batchBarrier":true},
+  {"name":"config edit","command":"git config --edit","certainty":"known","writes":["repository"],"permissionReader":false,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":true,"contentMutation":false,"batchBarrier":true},
+  {"name":"config global edit","command":"git config --global -e","certainty":"known","writes":["host"],"permissionReader":false,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":true,"contentMutation":false,"batchBarrier":true},
+  {"name":"pure commit","command":"git commit -q -m private-operand","certainty":"known","writes":["repository"],"permissionReader":false,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":true,"contentMutation":false,"batchBarrier":true},
+  {"name":"commit all","command":"git commit -am private-operand","certainty":"known","writes":["content","repository"],"permissionReader":false,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":true,"contentMutation":true,"batchBarrier":true},
+  {"name":"date display","command":"date -u +%s","certainty":"known","writes":[],"permissionReader":true,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":false,"contentMutation":false,"batchBarrier":false},
+  {"name":"date set","command":"date --set private-operand","certainty":"known","writes":["host"],"permissionReader":false,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":true,"contentMutation":false,"batchBarrier":true},
+  {"name":"npm audit","command":"npm audit","certainty":"known","writes":[],"permissionReader":true,"executesCode":false,"usesNetwork":true,"taskPolicyBlocked":false,"contentMutation":false,"batchBarrier":false},
+  {"name":"npm audit fix","command":"npm audit fix","certainty":"known","writes":["content"],"permissionReader":false,"executesCode":false,"usesNetwork":true,"taskPolicyBlocked":true,"contentMutation":true,"batchBarrier":true},
+  {"name":"go list readonly","command":"go list -mod=readonly ./...","certainty":"known","writes":[],"permissionReader":true,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":false,"contentMutation":false,"batchBarrier":false},
+  {"name":"go list mod","command":"go list -mod=mod ./...","certainty":"known","writes":["content"],"permissionReader":false,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":true,"contentMutation":true,"batchBarrier":true},
+  {"name":"cargo check","command":"cargo check","certainty":"known","writes":["content"],"permissionReader":false,"executesCode":true,"usesNetwork":false,"taskPolicyBlocked":true,"contentMutation":true,"batchBarrier":true},
+  {"name":"safe pipeline","command":"git branch -a | head -10","certainty":"known","writes":[],"permissionReader":true,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":false,"contentMutation":false,"batchBarrier":false},
+  {"name":"reader and writer","command":"git status && git tag private-operand","certainty":"known","writes":["repository"],"permissionReader":false,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":true,"contentMutation":false,"batchBarrier":true},
+  {"name":"dynamic expansion","command":"echo $DYNAMIC_VALUE","certainty":"unknown","writes":[],"permissionReader":false,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":true,"contentMutation":true,"batchBarrier":true},
+  {"name":"background job","command":"git status &","certainty":"unknown","writes":[],"permissionReader":false,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":true,"contentMutation":true,"batchBarrier":true},
+  {"name":"negated reader","command":"! git status","certainty":"unknown","writes":[],"permissionReader":false,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":true,"contentMutation":true,"batchBarrier":true},
+  {"name":"assignment wrapper","command":"FOO=bar git status","certainty":"known","writes":[],"permissionReader":false,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":false,"contentMutation":false,"batchBarrier":false},
+  {"name":"subshell","command":"(ls -la)","certainty":"unknown","writes":[],"permissionReader":false,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":true,"contentMutation":true,"batchBarrier":true},
+  {"name":"heredoc","command":"cat <<EOF\nhello\nEOF","certainty":"unknown","writes":[],"permissionReader":false,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":true,"contentMutation":true,"batchBarrier":true},
+  {"name":"find listing","command":"find . -name '*.go'","certainty":"known","writes":[],"permissionReader":true,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":false,"contentMutation":false,"batchBarrier":false},
+  {"name":"find delete","command":"find . -delete","certainty":"known","writes":["content"],"permissionReader":false,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":true,"contentMutation":true,"batchBarrier":true},
+  {"name":"find exec","command":"find . -exec rm {} ;","certainty":"unknown","writes":[],"permissionReader":false,"executesCode":true,"usesNetwork":false,"taskPolicyBlocked":true,"contentMutation":true,"batchBarrier":true},
+  {"name":"sort output","command":"sort --output=out f","certainty":"known","writes":["content"],"permissionReader":false,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":true,"contentMutation":true,"batchBarrier":true},
+  {"name":"go env write","command":"go env -w GOFLAGS=-mod=mod","certainty":"known","writes":["host"],"permissionReader":false,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":true,"contentMutation":false,"batchBarrier":true},
+  {"name":"git log output","command":"git log --output=history.patch","certainty":"known","writes":["content"],"permissionReader":false,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":true,"contentMutation":true,"batchBarrier":true},
+  {"name":"bare tag list","command":"git tag","certainty":"known","writes":[],"permissionReader":true,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":false,"contentMutation":false,"batchBarrier":false},
+  {"name":"annotated tag","command":"git tag -a v1.0","certainty":"known","writes":["repository"],"permissionReader":false,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":true,"contentMutation":false,"batchBarrier":true},
+  {"name":"env prefixed reader","command":"GOROOT=/x git status","certainty":"known","writes":[],"permissionReader":false,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":false,"contentMutation":false,"batchBarrier":false},
+  {"name":"env utility reader","command":"env GOROOT=/x git status","certainty":"known","writes":[],"permissionReader":false,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":false,"contentMutation":false,"batchBarrier":false},
+  {"name":"env flags","command":"env -i git status","certainty":"unknown","writes":[],"permissionReader":false,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":true,"contentMutation":true,"batchBarrier":true},
+  {"name":"dynamic env assignment","command":"FOO=$(whoami) git status","certainty":"unknown","writes":[],"permissionReader":false,"executesCode":false,"usesNetwork":false,"taskPolicyBlocked":true,"contentMutation":true,"batchBarrier":true}
+]

release-notes/releases.json

@@ -1,6 +1,490 @@
 {
   "schemaVersion": 1,
   "releases": [
+    {
+      "version": "1.25.0",
+      "date": "2026-08-13",
+      "channel": "stable",
+      "title": {
+        "en": "Desktop 1.25.0",
+        "zh": "桌面版 1.25.0"
+      },
+      "summary": {
+        "en": "Fixes for streaming markdown rendering, transcript layout and session switching, plus improvements to command safety classification and agent progress tracking.",
+        "zh": "修复流式 Markdown 渲染、对话布局和会话切换问题，并改进命令安全分类和智能体进度跟踪。"
+      },
+      "surfaces": [
+        "desktop"
+      ],
+      "guides": [],
+      "highlights": [
+        {
+          "kind": "fixed",
+          "title": {
+            "en": "Streaming lists render completed items immediately",
+            "zh": "流式列表立即渲染已完成项"
+          },
+          "body": {
+            "en": "Tight markdown lists no longer flash raw source while answers stream; completed items now render as they arrive.",
+            "zh": "紧凑的 Markdown 列表在答案流式传输时不再闪现原始源码；已完成项现在会随到达即时渲染。"
+          },
+          "refs": [
+            8669
+          ]
+        },
+        {
+          "kind": "fixed",
+          "title": {
+            "en": "Transcript layout fixes for scrolling and workspace dock",
+            "zh": "修复滚动和工作区停靠栏的对话布局"
+          },
+          "body": {
+            "en": "Fixed overlapping text when scrolling up, cropped user bubbles when the workspace dock is open, and ghost bubbles in short chats.",
+            "zh": "修复了向上滚动时文本重叠、打开工作区停靠栏时用户气泡被裁切以及短对话中的幽灵气泡问题。"
+          },
+          "refs": [
+            8659,
+            8660,
+            8663
+          ]
+        },
+        {
+          "kind": "fixed",
+          "title": {
+            "en": "Thinking transcript restored after session switch",
+            "zh": "会话切换后恢复思考中的对话记录"
+          },
+          "body": {
+            "en": "Switching back to a conversation that is still thinking now shows the live transcript instead of the welcome screen.",
+            "zh": "切换回仍在思考的对话时，现在会显示实时对话记录，而不是欢迎屏幕。"
+          },
+          "refs": [
+            8665
+          ]
+        },
+        {
+          "kind": "improved",
+          "title": {
+            "en": "Smarter command safety classification",
+            "zh": "更智能的命令安全分类"
+          },
+          "body": {
+            "en": "Command effects are now classified with argument-aware rules, reducing false positives for read-only commands and correctly blocking mutating ones.",
+            "zh": "命令效果现在使用参数感知规则进行分类，减少只读命令的误报，并正确阻止有变更的命令。"
+          },
+          "refs": [
+            8417,
+            8012
+          ]
+        },
+        {
+          "kind": "improved",
+          "title": {
+            "en": "Agent progress tracking based on actual progress",
+            "zh": "基于实际进度的智能体进度跟踪"
+          },
+          "body": {
+            "en": "The no-progress guard now prices a turn's progress instead of counting rounds, allowing honest investigation to continue longer.",
+            "zh": "无进展防护现在根据回合的实际进展来评估，而不是计算轮数，让诚实的调查可以持续更长时间。"
+          },
+          "refs": [
+            8404,
+            8407
+          ]
+        },
+        {
+          "kind": "new",
+          "title": {
+            "en": "DeepSeek Responses preset now includes Pro model",
+            "zh": "DeepSeek Responses 预设现在包含 Pro 模型"
+          },
+          "body": {
+            "en": "The official DeepSeek Responses preset now supports deepseek-v4-pro alongside deepseek-v4-flash, with automatic upgrade for existing configs.",
+            "zh": "官方 DeepSeek Responses 预设现在支持 deepseek-v4-pro 和 deepseek-v4-flash，并自动升级现有配置。"
+          },
+          "refs": [
+            8654
+          ]
+        }
+      ],
+      "changes": {
+        "new": [
+          {
+            "title": {
+              "en": "DeepSeek Responses preset extended to Pro",
+              "zh": "DeepSeek Responses 预设扩展支持 Pro"
+            },
+            "body": {
+              "en": "The official DeepSeek Responses preset now includes deepseek-v4-pro with per-model pricing and reasoning-effort overrides.",
+              "zh": "官方 DeepSeek Responses 预设现在包含 deepseek-v4-pro，并带有按模型定价和推理力度覆盖。"
+            },
+            "refs": [
+              8654
+            ]
+          }
+        ],
+        "improved": [
+          {
+            "title": {
+              "en": "Command effect classification unified",
+              "zh": "统一命令效果分类"
+            },
+            "body": {
+              "en": "Replaced coarse read-only boolean with argument-aware CommandEffect model, fixing misclassification of commands like git branch -a and git commit.",
+              "zh": "用参数感知的 CommandEffect 模型替换了粗略的只读布尔值，修复了 git branch -a 和 git commit 等命令的误分类。"
+            },
+            "refs": [
+              8417,
+              8012
+            ]
+          },
+          {
+            "title": {
+              "en": "Agent progress guard now prices progress",
+              "zh": "智能体进度防护现在评估进度"
+            },
+            "body": {
+              "en": "The no-progress guard uses a per-turn account that rewards new observations and landed changes, avoiding premature stops.",
+              "zh": "无进展防护使用按回合账户，奖励新观察和已落地的更改，避免过早停止。"
+            },
+            "refs": [
+              8404,
+              8407
+            ]
+          },
+          {
+            "title": {
+              "en": "Tool calls get explicit execution environment",
+              "zh": "工具调用获得显式执行环境"
+            },
+            "body": {
+              "en": "Introduced tool.ExecutionEnv to pass capabilities explicitly instead of through context, reducing silent degradation.",
+              "zh": "引入 tool.ExecutionEnv 以显式传递能力，而不是通过上下文，减少静默降级。"
+            },
+            "refs": [
+              8614
+            ]
+          }
+        ],
+        "fixed": [
+          {
+            "title": {
+              "en": "Streaming list rendering fixed",
+              "zh": "修复流式列表渲染"
+            },
+            "body": {
+              "en": "Completed list items now render during streaming instead of showing raw markdown source.",
+              "zh": "已完成的列表项现在在流式传输期间渲染，而不是显示原始 Markdown 源码。"
+            },
+            "refs": [
+              8669
+            ]
+          },
+          {
+            "title": {
+              "en": "Transcript layout fixes",
+              "zh": "修复对话布局"
+            },
+            "body": {
+              "en": "Fixed overlapping text when scrolling up, cropped user bubbles with workspace dock open, and ghost bubbles in short chats.",
+              "zh": "修复了向上滚动时文本重叠、打开工作区停靠栏时用户气泡被裁切以及短对话中的幽灵气泡问题。"
+            },
+            "refs": [
+              8659,
+              8660,
+              8663
+            ]
+          },
+          {
+            "title": {
+              "en": "Thinking transcript restored after session switch",
+              "zh": "会话切换后恢复思考中的对话记录"
+            },
+            "body": {
+              "en": "Switching back to a thinking conversation now shows the live transcript instead of the welcome screen.",
+              "zh": "切换回思考中的对话时，现在会显示实时对话记录，而不是欢迎屏幕。"
+            },
+            "refs": [
+              8665
+            ]
+          }
+        ]
+      },
+      "upgrade": [],
+      "risks": [],
+      "contributors": [
+        "SivanCola",
+        "innocarpe",
+        "bfxh",
+        "esengine"
+      ],
+      "links": {
+        "github": "https://github.com/esengine/DeepSeek-Reasonix/releases/tag/desktop-v1.25.0",
+        "compare": "https://github.com/esengine/DeepSeek-Reasonix/compare/desktop-v1.24.2...desktop-v1.25.0",
+        "download": "https://reasonix.io/?download=desktop&channel=stable#start"
+      },
+      "releaseId": "1.25.0",
+      "baseVersion": "1.25.0",
+      "status": "reviewed",
+      "previousRelease": "1.24.2",
+      "builds": {
+        "cli": "v1.25.0",
+        "desktop": "v1.25.0",
+        "npm": "1.25.0"
+      }
+    },
+    {
+      "version": "1.24.2",
+      "date": "2026-08-12",
+      "channel": "stable",
+      "title": {
+        "en": "Reasonix Desktop 1.24.2",
+        "zh": "Reasonix Desktop 1.24.2"
+      },
+      "summary": {
+        "en": "Stability and recovery improvements for session persistence, transcript scrolling, and Windows startup.",
+        "zh": "会话持久化、对话滚动和 Windows 启动的稳定性与恢复改进。"
+      },
+      "surfaces": [
+        "desktop"
+      ],
+      "guides": [
+        {
+          "title": {
+            "en": "Session Catalog",
+            "zh": "会话目录"
+          },
+          "body": {
+            "en": "Learn how the session catalog organizes recovery copies and logical sessions.",
+            "zh": "了解会话目录如何组织恢复副本和逻辑会话。"
+          },
+          "href": "https://github.com/esengine/DeepSeek-Reasonix/blob/f53edb599a929afe0c6fa514c8e441899c166afc/docs/SESSION_CATALOG.md"
+        },
+        {
+          "title": {
+            "en": "Configuration Paths",
+            "zh": "配置路径"
+          },
+          "body": {
+            "en": "Reference for configuration file locations and environment variables.",
+            "zh": "配置文件位置和环境变量参考。"
+          },
+          "href": "https://github.com/esengine/DeepSeek-Reasonix/blob/f53edb599a929afe0c6fa514c8e441899c166afc/docs/CONFIG_PATHS.md"
+        }
+      ],
+      "highlights": [
+        {
+          "kind": "fixed",
+          "title": {
+            "en": "Recovery lineages now appear as a single logical session",
+            "zh": "恢复谱系现在显示为单个逻辑会话"
+          },
+          "body": {
+            "en": "Recovery copies are folded into one ordinary list row, preventing duplicate-looking sessions after upgrades.",
+            "zh": "恢复副本折叠为单个普通列表行，防止升级后出现重复会话。"
+          },
+          "refs": [
+            8599
+          ]
+        },
+        {
+          "kind": "fixed",
+          "title": {
+            "en": "Sidebar no longer freezes on a wedged projection",
+            "zh": "侧边栏不再因投影卡死而冻结"
+          },
+          "body": {
+            "en": "Bounded sidebar reads and background metadata sync prevent permanent freezes when the session catalog pool is saturated.",
+            "zh": "限制侧边栏读取和后台元数据同步，防止会话目录连接池饱和时永久冻结。"
+          },
+          "refs": [
+            8594
+          ]
+        },
+        {
+          "kind": "fixed",
+          "title": {
+            "en": "Stable transcript scrolling during async row growth",
+            "zh": "异步行高变化时对话滚动稳定"
+          },
+          "body": {
+            "en": "React Virtuoso now owns virtual measurement, preventing jumps when Markdown or code blocks finish loading.",
+            "zh": "React Virtuoso 现在负责虚拟测量，防止 Markdown 或代码块加载完成时跳动。"
+          },
+          "refs": [
+            8492,
+            8429,
+            8586
+          ]
+        },
+        {
+          "kind": "fixed",
+          "title": {
+            "en": "Windows startup no longer flashes console windows",
+            "zh": "Windows 启动不再闪现控制台窗口"
+          },
+          "body": {
+            "en": "Startup git probes now use the hardened command wrapper, hiding console windows.",
+            "zh": "启动时的 git 探测现在使用加固的命令包装器，隐藏控制台窗口。"
+          },
+          "refs": [
+            8425
+          ]
+        },
+        {
+          "kind": "fixed",
+          "title": {
+            "en": "Lifecycle records are no longer lost to Windows sharing violations",
+            "zh": "生命周期记录不再因 Windows 共享冲突而丢失"
+          },
+          "body": {
+            "en": "Retry logic for rename and re-read operations ensures crash evidence is preserved when multiple instances start together.",
+            "zh": "重命名和重读操作的重试逻辑确保多个实例同时启动时保留崩溃证据。"
+          },
+          "refs": [
+            8550
+          ]
+        },
+        {
+          "kind": "fixed",
+          "title": {
+            "en": "Projection lineage rebinds across upgrades and model switches",
+            "zh": "投影 lineage 在升级和模型切换时重新绑定"
+          },
+          "body": {
+            "en": "Context projections are preserved when the lineage key changes, avoiding full-price compaction on resume.",
+            "zh": "当 lineage 键变化时保留上下文投影，避免恢复时全价压缩。"
+          },
+          "refs": [
+            8390,
+            8400
+          ]
+        },
+        {
+          "kind": "fixed",
+          "title": {
+            "en": "Recovery forks no longer multiply without bound",
+            "zh": "恢复分支不再无限增长"
+          },
+          "body": {
+            "en": "False diverged forks are prevented and depth-cap isolation is bounded to one file per writer.",
+            "zh": "防止误判 diverged 分支，并将深度上限隔离限制为每个写入者一个文件。"
+          },
+          "refs": [
+            8444,
+            8430,
+            8457,
+            7982
+          ]
+        }
+      ],
+      "changes": {
+        "new": [],
+        "improved": [
+          {
+            "title": {
+              "en": "Session catalog now uses a disposable v4 database",
+              "zh": "会话目录现在使用一次性 v4 数据库"
+            },
+            "body": {
+              "en": "Logical projection and recovery roles are rebuilt from authoritative content, preventing cross-version write conflicts.",
+              "zh": "逻辑投影和恢复角色从权威内容重建，防止跨版本写入冲突。"
+            },
+            "refs": [
+              8599,
+              8425
+            ]
+          },
+          {
+            "title": {
+              "en": "Agent state refactored for clarity and safety",
+              "zh": "Agent 状态重构以提高清晰度和安全性"
+            },
+            "body": {
+              "en": "Collaborators, configuration, and runtime lifetimes are separated, with guard tests preventing accidental state changes.",
+              "zh": "协作者、配置和运行时生命周期分离，并通过保护测试防止意外状态更改。"
+            },
+            "refs": [
+              8595,
+              8564,
+              8588,
+              8541,
+              8485,
+              8460,
+              8453,
+              8447,
+              8439
+            ]
+          },
+          {
+            "title": {
+              "en": "Compaction failure records preserved across folds",
+              "zh": "压缩失败记录在多次折叠中保留"
+            },
+            "body": {
+              "en": "Projection re-reads now keep tool execution details, so the model continues to see failure context.",
+              "zh": "投影重读现在保留工具执行细节，模型继续看到失败上下文。"
+            },
+            "refs": [
+              8432
+            ]
+          }
+        ],
+        "fixed": [
+          {
+            "title": {
+              "en": "Recovery copy classification restored",
+              "zh": "恢复副本分类恢复"
+            },
+            "body": {
+              "en": "Covered recovery copies are hidden from the project tree, reducing duplicate-looking sessions.",
+              "zh": "隐藏已覆盖的恢复副本，减少重复会话。"
+            },
+            "refs": [
+              8425
+            ]
+          },
+          {
+            "title": {
+              "en": "Repolint baseline corrected",
+              "zh": "Repolint 基线修正"
+            },
+            "body": {
+              "en": "Generated bindings are excluded from measurement and stale budgets are resynced.",
+              "zh": "生成的绑定从测量中排除，过时的预算重新同步。"
+            },
+            "refs": [
+              8605,
+              8503,
+              8436
+            ]
+          }
+        ]
+      },
+      "upgrade": [],
+      "risks": [],
+      "contributors": [
+        "SivanCola",
+        "yingziisme",
+        "esengine",
+        "erphenheimer",
+        "Drummerms"
+      ],
+      "links": {
+        "github": "https://github.com/esengine/DeepSeek-Reasonix/releases/tag/desktop-v1.24.2",
+        "compare": "https://github.com/esengine/DeepSeek-Reasonix/compare/desktop-v1.24.1...desktop-v1.24.2",
+        "download": "https://reasonix.io/?download=desktop&channel=stable#start"
+      },
+      "releaseId": "1.24.2",
+      "baseVersion": "1.24.2",
+      "status": "reviewed",
+      "previousRelease": "1.24.1",
+      "builds": {
+        "cli": "v1.24.2",
+        "desktop": "v1.24.2",
+        "npm": "1.24.2"
+      }
+    },
     {
       "version": "1.24.1",
       "date": "2026-08-11",

tools/repolint/baseline.json

@@ -2,15 +2,15 @@
   "limits": {
     "banner": 15,
     "commented-code": 0,
-    "complexity": 2069,
-    "essay": 3983,
-    "file-size": 108119,
-    "function-size": 8846,
+    "complexity": 2109,
+    "essay": 4001,
+    "file-size": 108398,
+    "function-size": 8934,
     "layering": 1,
     "marker": 0,
     "narrative": 64,
     "struct-state": 115,
-    "test-file-size": 69236
+    "test-file-size": 69269
   },
   "files": {
     "cmd/e2ebench/main.go": {
@@ -130,6 +130,9 @@
     "desktop/frontend/src/components/ContextPanel.tsx": {
       "file-size": 38
     },
+    "desktop/frontend/src/components/HistoryPanel.tsx": {
+      "file-size": 65
+    },
     "desktop/frontend/src/components/MemoryPanel.tsx": {
       "file-size": 1088
     },
@@ -137,7 +140,7 @@
       "file-size": 95
     },
     "desktop/frontend/src/components/ProjectTree.tsx": {
-      "file-size": 1475
+      "file-size": 1474
     },
     "desktop/frontend/src/components/RichComposerInput.tsx": {
       "file-size": 141
@@ -155,7 +158,7 @@
       "file-size": 158
     },
     "desktop/frontend/src/components/Transcript.tsx": {
-      "file-size": 278
+      "file-size": 280
     },
     "desktop/frontend/src/components/UsageStatsPanel.tsx": {
       "file-size": 276
@@ -167,7 +170,7 @@
       "file-size": 415
     },
     "desktop/frontend/src/lib/bridge.ts": {
-      "file-size": 4756
+      "file-size": 4780
     },
     "desktop/frontend/src/lib/crash.ts": {
       "file-size": 225
@@ -176,7 +179,7 @@
       "file-size": 269
     },
     "desktop/frontend/src/lib/types.ts": {
-      "file-size": 1527
+      "file-size": 1578
     },
     "desktop/frontend/src/lib/useController.ts": {
       "file-size": 3969
@@ -235,6 +238,9 @@
     "desktop/race_regression_test.go": {
       "essay": 4
     },
+    "desktop/recovery_gc.go": {
+      "essay": 2
+    },
     "desktop/recovery_gc_test.go": {
       "essay": 1
     },
@@ -255,6 +261,12 @@
     "desktop/runtime_rebuilt_event_test.go": {
       "essay": 1
     },
+    "desktop/session_catalog_app_test.go": {
+      "essay": 1
+    },
+    "desktop/session_catalog_runtime.go": {
+      "essay": 2
+    },
     "desktop/session_errors.go": {
       "essay": 1
     },
@@ -310,7 +322,7 @@
     "desktop/tabs.go": {
       "complexity": 41,
       "essay": 111,
-      "file-size": 7704,
+      "file-size": 7708,
       "function-size": 369,
       "struct-state": 23
     },
@@ -322,7 +334,7 @@
     },
     "desktop/tabs_topic_test.go": {
       "essay": 1,
-      "test-file-size": 3250
+      "test-file-size": 3261
     },
     "desktop/temphelper_test.go": {
       "essay": 4
@@ -572,7 +584,8 @@
       "essay": 8
     },
     "internal/agent/recovery_gc.go": {
-      "essay": 17
+      "essay": 17,
+      "file-size": 60
     },
     "internal/agent/recovery_gc_test.go": {
       "essay": 1
@@ -590,14 +603,14 @@
       "essay": 5
     },
     "internal/agent/save.go": {
-      "complexity": 36,
+      "complexity": 37,
       "essay": 109,
-      "file-size": 1466,
-      "function-size": 102
+      "file-size": 1488,
+      "function-size": 105
     },
     "internal/agent/save_test.go": {
       "essay": 9,
-      "test-file-size": 1946
+      "test-file-size": 1968
     },
     "internal/agent/scheduler.go": {
       "essay": 1
@@ -940,12 +953,16 @@
     "internal/cli/session_lease.go": {
       "essay": 4
     },
+    "internal/cli/sessions_catalog.go": {
+      "complexity": 10,
+      "function-size": 3
+    },
     "internal/cli/setup_manager.go": {
       "essay": 2,
       "file-size": 126
     },
     "internal/cli/shell_completion.go": {
-      "function-size": 113
+      "function-size": 119
     },
     "internal/cli/skill_hooks.go": {
       "essay": 1
@@ -1088,8 +1105,8 @@
     "internal/control/controller.go": {
       "complexity": 10,
       "essay": 161,
-      "file-size": 5489,
-      "function-size": 75,
+      "file-size": 5529,
+      "function-size": 82,
       "narrative": 4,
       "struct-state": 17
     },
@@ -1755,6 +1772,20 @@
     "internal/serve/switch_recovery_test.go": {
       "essay": 2
     },
+    "internal/sessioncatalog/catalog.go": {
+      "file-size": 3
+    },
+    "internal/sessioncatalog/lineage.go": {
+      "complexity": 29,
+      "essay": 4,
+      "function-size": 69
+    },
+    "internal/sessioncatalog/ordinary_visibility.go": {
+      "essay": 9
+    },
+    "internal/sessioncatalog/reconcile.go": {
+      "file-size": 9
+    },
     "internal/sessiontemp/manager.go": {
       "essay": 5
     },