@stigmer/react 3.1.1 → 3.1.3

package/src/session/{inspector → facets}/index.ts

@@ -1,13 +1,3 @@
-export { SessionInspector } from "./SessionInspector.js";
-export type { SessionInspectorProps } from "./SessionInspector.js";
-
-export { useSessionInspector, buildVisibleTabs } from "./useSessionInspector.js";
-export type {
-  SessionInspectorTabId,
-  UseSessionInspectorOptions,
-  UseSessionInspectorReturn,
-} from "./useSessionInspector.js";
-
 export { ChangesTab } from "./ChangesTab.js";
 export type { ChangesTabProps } from "./ChangesTab.js";
 
@@ -25,9 +15,3 @@ export type {
   SetupTabProps,
   SetupTabMutationCallbacks,
 } from "./SetupTab.js";
-
-export { WorkspaceTab } from "./WorkspaceTab.js";
-export type {
-  WorkspaceTabProps,
-  WorkspaceTabActions,
-} from "./WorkspaceTab.js";

package/src/session/index.ts

@@ -102,24 +102,41 @@ export type { SessionViewerProps } from "./SessionViewer.js";
 export { NewSessionViewer } from "./NewSessionViewer.js";
 export type { NewSessionViewerProps } from "./NewSessionViewer.js";
 
-// Selection types (for platform builders using SessionInspector directly)
+// Unified session-panel controller — drives the WorkspaceSurface open-editor
+// group, the collapsed/open state, and the rail-view FSM (for platform
+// builders embedding the surface directly).
+export { useSessionPanel } from "./useSessionPanel.js";
+export type {
+  SessionPanelController,
+  UseSessionPanelOptions,
+} from "./useSessionPanel.js";
+
+// Plan draft — viewer-owned in-place edit of the session's current plan
+// (edit-as-input; the published plan.md artifact is never mutated).
+export { usePlanDraft, planDraftKey } from "./usePlanDraft.js";
+export type { PlanDraftController } from "./usePlanDraft.js";
+
+// Plan document — the editor-area plan surface (mounted as a virtual document
+// in the workspace surface) and the identity of its tab.
+export { PlanEditor } from "./PlanEditor.js";
+export type { PlanEditorProps } from "./PlanEditor.js";
+export { PlanStreamingDocument } from "./PlanStreamingDocument.js";
+export type { PlanStreamingDocumentProps } from "./PlanStreamingDocument.js";
+export {
+  PLAN_DOCUMENT_ENTRY_ID,
+  PLAN_DOCUMENT_PATH,
+} from "./plan-document.js";
+
+// Selection types (for platform builders composing their own Inspect facet)
 export type { SelectedThreadItem } from "../internal/store/selection-store.js";
 
-// SessionInspector — tabbed right-side inspector panel
-export {
-  SessionInspector,
-  useSessionInspector,
-  buildVisibleTabs,
-  SetupTab,
-} from "./inspector/index.js";
+// Session facet components — the panel's rail views (Config et al.), also
+// independently importable (DD-003).
+export { SetupTab } from "./facets/index.js";
 export type {
-  SessionInspectorProps,
-  SessionInspectorTabId,
-  UseSessionInspectorOptions,
-  UseSessionInspectorReturn,
   SetupTabProps,
   SetupTabMutationCallbacks,
-} from "./inspector/index.js";
+} from "./facets/index.js";
 
 // Session utilities (re-exported from @stigmer/sdk)
 export { PENDING_SUBJECT, resolvedSubject } from "@stigmer/sdk";

package/src/session/plan-document.ts

@@ -0,0 +1,30 @@
+// Identity of the session's plan tab in the workspace surface's editor group.
+//
+// Kept in its own module (not in PlanEditor.tsx) so behavior-only consumers —
+// useSessionPanel opens the tab, SessionViewer routes to it — depend on the
+// identity without pulling the component (and its markdown renderer) into
+// their module graph (DD-003 headless-first).
+
+import { virtualEntryId } from "../internal/store/index.js";
+
+/**
+ * Virtual entry id of the plan document tab. One tab per session — the host
+ * swaps WHICH plan the tab shows (latest editable, or a superseded plan
+ * read-only); the tab itself never multiplies.
+ */
+export const PLAN_DOCUMENT_ENTRY_ID = virtualEntryId("plan");
+
+/**
+ * The plan tab's path — doubles as its tab label.
+ *
+ * Deliberately plan-AGNOSTIC ("Plan"), not the artifact's filename. The
+ * workspace surface identifies a virtual document's tab by
+ * `editorKey(entryId, path)`, so `path` is part of the tab's IDENTITY — and the
+ * session keeps exactly ONE plan tab that swaps which plan it shows (latest
+ * editable, or a superseded plan read-only). Now that plans carry unique,
+ * title-derived filenames (`<slug>_<id>.plan.md`), binding this label to any one
+ * plan's name would mint a new tab identity per plan and shatter the
+ * single-tab design. A stable, generic label is therefore required, not a
+ * stylistic choice — do not "fix" it to track the filename.
+ */
+export const PLAN_DOCUMENT_PATH = "Plan";

package/src/session/useOpenFileChange.ts

@@ -0,0 +1,53 @@
+"use client";
+
+import { useMemo } from "react";
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { FileChange } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import type { WorkspaceEntry } from "../workspace/useWorkspaceEntries.js";
+import type { SelectedWorkspaceFile } from "../internal/store/workspace-file-selection-store.js";
+import { findChangeForSelection } from "../workspace/findChangeForSelection.js";
+import { useSessionFileChanges } from "./useSessionFileChanges.js";
+
+/**
+ * Stable empty executions passed to {@link useSessionFileChanges} while no file
+ * is open, so the (fetch-free) net-change fold stays trivial during streaming
+ * and only folds once a file is actually being viewed.
+ */
+const EMPTY_EXECUTIONS: readonly AgentExecution[] = [];
+
+/**
+ * Correlate the open workspace file with the one session {@link FileChange} that
+ * touched it, so a changed file can default to its authoritative
+ * `baseline→candidate` diff (Slice 4 / DD-06).
+ *
+ * The net-change fold is skipped while no file is open (via `EMPTY_EXECUTIONS`),
+ * and the join reuses the same DD-08 resolver + entries + sandbox root that
+ * opened the file — so "the diff shown" can never disagree with "the file
+ * opened". Both the inspector's Viewer tab and the workspace surface consume
+ * this single hook rather than re-deriving the correlation.
+ *
+ * @returns the matching change, or `null` when the open file was not changed
+ *   this session (or no file is open).
+ */
+export function useOpenFileChange(
+  selectedFile: SelectedWorkspaceFile | null | undefined,
+  allExecutions: readonly AgentExecution[],
+  entries: readonly WorkspaceEntry[] | undefined,
+  sandboxWorkspaceRoot: string | undefined,
+): FileChange | null {
+  const { fileChanges } = useSessionFileChanges(
+    selectedFile ? allExecutions : EMPTY_EXECUTIONS,
+  );
+  return useMemo(
+    () =>
+      selectedFile && entries
+        ? findChangeForSelection(
+            selectedFile,
+            fileChanges,
+            entries,
+            sandboxWorkspaceRoot,
+          ) ?? null
+        : null,
+    [selectedFile, fileChanges, entries, sandboxWorkspaceRoot],
+  );
+}

package/src/session/usePlanDraft.ts

@@ -0,0 +1,109 @@
+"use client";
+
+import { useCallback, useMemo, useRef, useState } from "react";
+import type { SessionPlan } from "../library/detect-plan-artifact.js";
+
+/**
+ * Identity of a plan for draft scoping: the execution that published it plus
+ * the artifact's content hash. A refined plan (new execution) or a republished
+ * plan (same key, new hash) produces a NEW identity, which orphans any draft
+ * of the previous plan — a draft of plan N must never silently ride along
+ * once plan N+1 exists.
+ */
+export function planDraftKey(plan: SessionPlan): string {
+  return `${plan.executionId}:${plan.artifact.contentHash}`;
+}
+
+/** Controller returned by {@link usePlanDraft}. */
+export interface PlanDraftController {
+  /**
+   * The user's in-place edit of the current plan, or `null` when the plan is
+   * unedited. Always scoped to the CURRENT plan — a draft made against a
+   * superseded plan reads as `null` here (it is dropped, never migrated).
+   */
+  readonly draftText: string | null;
+  /** True when the current plan has an active draft. */
+  readonly isEdited: boolean;
+  /**
+   * Set (or update) the draft for the current plan. Pass `null` to revert to
+   * the published plan. No-ops when the session has no plan.
+   */
+  readonly setDraft: (text: string | null) => void;
+  /**
+   * Snapshot reader for submit-time consumers: returns the current draft (or
+   * `null`) without the caller depending on draft state. Referentially stable
+   * for the lifetime of the component (DD-010) — the "Build" action reads the
+   * draft through this at click time, so per-keystroke draft updates never
+   * re-bind the build callback or re-render the conversation column.
+   */
+  readonly readDraft: () => string | null;
+}
+
+interface DraftState {
+  readonly key: string;
+  readonly text: string;
+}
+
+/**
+ * Owns the local draft of the session's current plan (Phase: refine before
+ * build). The draft is a client-side overlay — the published `plan.md`
+ * artifact is immutable and is never written back (edit-as-input, not
+ * artifact mutation). The approved plan (draft if edited, else the artifact
+ * text) is delivered to the implement execution as an attachment.
+ *
+ * Ownership lives at the viewer level, NOT inside the plan document tab's
+ * editor: the panel subtree unmounts wholesale on collapse (and the editor
+ * remounts per plan identity), so editor-local state would be destroyed by
+ * every collapse or tab switch — silently losing the user's edits.
+ *
+ * Supersession is derived, not synchronized: the draft is stored with the
+ * plan identity it was made against ({@link planDraftKey}), and reads resolve
+ * against the CURRENT plan's identity. When a newer plan arrives the old
+ * draft simply stops matching — no effect, no cleanup, no stale-flush race.
+ */
+export function usePlanDraft(
+  plan: SessionPlan | undefined,
+): PlanDraftController {
+  const [draft, setDraftState] = useState<DraftState | null>(null);
+
+  const currentKey = plan ? planDraftKey(plan) : null;
+  const draftText =
+    draft !== null && currentKey !== null && draft.key === currentKey
+      ? draft.text
+      : null;
+
+  // Render-synced mirrors so `readDraft` stays referentially stable while
+  // always observing the latest draft/plan (the useSessionPanel viewRef
+  // pattern).
+  const draftRef = useRef(draft);
+  draftRef.current = draft;
+  const currentKeyRef = useRef(currentKey);
+  currentKeyRef.current = currentKey;
+
+  const setDraft = useCallback(
+    (text: string | null) => {
+      const key = currentKeyRef.current;
+      if (!key) return;
+      setDraftState(text === null ? null : { key, text });
+    },
+    [],
+  );
+
+  const readDraft = useCallback((): string | null => {
+    const current = draftRef.current;
+    const key = currentKeyRef.current;
+    return current !== null && key !== null && current.key === key
+      ? current.text
+      : null;
+  }, []);
+
+  return useMemo(
+    () => ({
+      draftText,
+      isEdited: draftText !== null,
+      setDraft,
+      readDraft,
+    }),
+    [draftText, setDraft, readDraft],
+  );
+}

package/src/session/useSessionConversation.ts

@@ -3,7 +3,7 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import type { PendingApproval } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
-import type { FileChangeSet } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import type { FileChangeProgress, FileChangeSet } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
 import { ApprovalAction, ExecutionPhase, FileChangeSetStatus, FileDecisionAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
 import type { McpServerUsage as ProtoMcpServerUsage } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
@@ -96,6 +96,12 @@ export interface SendFollowUpOptions {
    * - `"plan"`: read-only analysis, no file mutations.
    */
   readonly interactionMode?: "agent" | "plan";
+  /**
+   * Marks this execution as a Build-from-plan turn.
+   *
+   * @see {@link CreateAgentExecutionInput.buildFromPlan}
+   */
+  readonly buildFromPlan?: boolean;
   /**
    * Auto-approve every tool call for this execution (bypass the HITL gate).
    *
@@ -216,6 +222,13 @@ export interface UseSessionConversationReturn {
 
   /** Captured change sets awaiting file review on the active execution, empty when none. */
   readonly fileChangeSets: readonly FileChangeSet[];
+  /**
+   * Mid-run live capture (DD-32): the transient, non-authoritative snapshot of the
+   * workspace delta accumulating during the active turn ("N files changed so far").
+   * Undefined when no turn is currently capturing. Never decidable — the reviewed
+   * diff is {@link fileChangeSets}.
+   */
+  readonly fileChangeProgress: FileChangeProgress | undefined;
   /** Submit a file-review decision for a change set. The executionId is managed internally. */
   readonly submitFileDecision: (
     changeSetId: string,
@@ -548,7 +561,14 @@ export function useSessionConversation(
       // Capture for retry and clear any prior failure before the new attempt.
       lastSendRef.current = { message, options };
       setSendError(null);
-      setPendingUserMessage(message);
+      // A Build-from-plan turn shows no optimistic bubble: its message is a
+      // machine-written label, not user prose, and the thread hides the turn
+      // entirely (the plan card's "Starting build…" state covers the send
+      // window). It is still set on FAILURE below, so a failed build send
+      // renders the failed-with-retry bubble instead of vanishing.
+      if (!options?.buildFromPlan) {
+        setPendingUserMessage(message);
+      }
 
       try {
         const needsSessionUpdate =
@@ -581,6 +601,7 @@ export function useSessionConversation(
           runtimeEnv: options?.runtimeEnv,
           attachments: options?.attachments,
           interactionMode: options?.interactionMode,
+          buildFromPlan: options?.buildFromPlan,
           autoApproveAll: options?.autoApproveAll,
           workspaceFileRefs: options?.workspaceFileRefs,
         });
@@ -589,7 +610,10 @@ export function useSessionConversation(
       } catch (err) {
         // Surface the failure and KEEP the user's message visible (do not clear
         // pendingUserMessage) so the turn renders as failed-with-retry instead
-        // of vanishing. Covers both the update() and create() paths.
+        // of vanishing. Covers both the update() and create() paths. For a
+        // build turn this is the FIRST time the message is set — failure is
+        // the one case where its label must become visible.
+        setPendingUserMessage(message);
         setSendError(toError(err));
         if (process.env.NODE_ENV !== "production") {
           console.error("[useSessionConversation] sendFollowUp failed:", err);
@@ -634,6 +658,16 @@ export function useSessionConversation(
     [activeStreamExecution],
   );
 
+  // Mid-run live capture (DD-32): the transient, non-authoritative "N files
+  // changed so far" snapshot for the active turn. The server clears it once the
+  // turn's change set leaves CAPTURING, so its mere presence means a turn is
+  // still accumulating changes. Reference-stable per DD-010 (it rides the
+  // structurally-shared live status).
+  const fileChangeProgress = useMemo<FileChangeProgress | undefined>(
+    () => activeStreamExecution?.status?.fileChangeProgress,
+    [activeStreamExecution],
+  );
+
   const submitFileDecision = useCallback(
     async (
       changeSetId: string,
@@ -678,6 +712,7 @@ export function useSessionConversation(
     clearApprovalError,
 
     fileChangeSets,
+    fileChangeProgress,
     submitFileDecision,
     submittingFileDecisionKeys: submittingDecisionKeys,
     fileDecisionErrors,

package/src/session/useSessionPageFlow.ts

@@ -405,6 +405,7 @@ export function useSessionPageFlow(
         runtimeEnv,
         attachments: context?.attachments,
         interactionMode: context?.interactionMode,
+        buildFromPlan: context?.buildFromPlan,
         // Sourced from the session-scoped preference set at the approval gate,
         // not from the composer (the pre-arm toggle was removed).
         autoApproveAll: autoApproveAll || undefined,

package/src/session/useSessionPanel.ts

@@ -0,0 +1,288 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { isTerminalPhase } from "../execution/execution-phases.js";
+import type { SelectedThreadItem } from "../internal/store/selection-store.js";
+import {
+  useWorkspaceEditorsStoreRef,
+  type OpenFileOptions,
+  type WorkspaceEditorsStore,
+} from "../internal/store/index.js";
+import { PLAN_DOCUMENT_ENTRY_ID, PLAN_DOCUMENT_PATH } from "./plan-document.js";
+
+/** Options for {@link useSessionPanel}. */
+export interface UseSessionPanelOptions {
+  /**
+   * The display execution's phase, or `null` before any execution exists.
+   * A transition between running and terminal resets the user's sticky view
+   * pick (mirroring the retired inspector-tab FSM).
+   */
+  readonly phase: ExecutionPhase | null;
+  /**
+   * Whether the session has git write-backs. The first arrival auto-surfaces
+   * the Changes view — but only while the panel is open; a collapsed panel
+   * signals through badges instead of pulling the user out of the chat.
+   */
+  readonly hasChanges: boolean;
+  /**
+   * Identity of the session's current plan, or `null` when none exists. Two
+   * identity families, supplied by the viewer: `<executionId>:streaming`
+   * while the active turn is WRITING a plan (see `findStreamingPlan`), then
+   * the published identity (`planDraftKey`) once the artifact exists. A NEW
+   * identity — a plan starting to stream, the first published plan, or a
+   * refined plan superseding it — auto-opens the plan document tab (see
+   * {@link SessionPanelController.openPlanDocument}), expanding a collapsed
+   * panel. This deliberately breaks the Changes/Inspect "never open a
+   * collapsed panel" convention: a plan is not ambient state, it is the
+   * deliverable of the turn the user just requested, and with the thread
+   * showing only a compact card there is no other review surface — live or
+   * settled. The streaming→published transition is itself a new identity,
+   * harmlessly re-firing the (idempotent) open as the tab's content settles.
+   * Keyed on plan IDENTITY, not presence, so a refined plan re-surfaces too;
+   * the identity present at mount is swallowed (loading a session with an
+   * old plan — or mid-stream — never hijacks the layout).
+   */
+  readonly planKey?: string | null;
+  /**
+   * The panel's home view — the view it opens on and the one every automatic
+   * reset returns to (running⇄terminal transition, selection cleared). Defaults
+   * to `"files"` (the Explorer), which suits the session viewer. The launcher
+   * passes `"configure"`: pre-session there is no workspace, so the Config
+   * facet — carrying the run defaults (harness/model) — is the useful landing
+   * view. Auto-switches (Changes/Inspect) and explicit rail picks still
+   * take over from here exactly as before.
+   *
+   * @default "files"
+   */
+  readonly defaultView?: string;
+}
+
+/**
+ * State + actions for the unified session panel, shared by every viewer that
+ * hosts it (session + launcher) so they behave identically (DD-016).
+ *
+ * The panel is the one right-side surface: a workspace surface whose activity
+ * rail hosts the session facets (see `useSessionRailViews`). It replaces the
+ * former two-view model (narrow inspector ⇄ workspace-mode flip): the panel is
+ * **collapsed by default** to a top-right chip, and `isOpen` + `view` describe
+ * it fully.
+ *
+ * Owns the {@link WorkspaceEditorsStore} (the open-editor group) and the view
+ * FSM ported from the retired inspector tabs: explicit picks are sticky until
+ * a meaningful state change (selection cleared, running⇄terminal transition)
+ * resets them back to the `defaultView`. Both are decoupled from any store
+ * subscription at the owner level: callbacks mutate imperatively so a file
+ * open/switch re-renders only the subscribing panel subtree, never the
+ * streaming conversation column (DD-009/DD-010, invariant 2).
+ */
+export interface SessionPanelController {
+  /** The open-editor group store; subscribe with `useWorkspaceEditors`. */
+  readonly editorsStore: WorkspaceEditorsStore;
+  /** Whether the panel is expanded (chat narrow) or collapsed to the chip. */
+  readonly isOpen: boolean;
+  /** The active rail view id (`"files"`, `"search"`, or an injected facet). */
+  readonly view: string;
+  /** Expand the panel, restoring the previous view (or Inspect if a thread item is selected). */
+  readonly openPanel: () => void;
+  /** Collapse the panel to the chip, preserving editors and view. */
+  readonly closePanel: () => void;
+  /** Explicit view pick from the rail — sticky against auto-switching. */
+  readonly setView: (viewId: string) => void;
+  /**
+   * Open a file as a preview tab and expand the panel. Pass `options.line` to
+   * jump to and highlight a specific 1-based line (e.g. a content-search hit) —
+   * the file opens in its line-faithful File view scrolled to that line.
+   */
+  readonly openFile: (
+    entryId: string,
+    path: string,
+    options?: OpenFileOptions,
+  ) => void;
+  /** Focus an already-open editor tab. */
+  readonly activateEditor: (entryId: string, path: string) => void;
+  /** Pin an editor tab (clear its preview state). */
+  readonly pinEditor: (entryId: string, path: string) => void;
+  /**
+   * Close an editor tab. The panel stays open even when the group empties —
+   * unlike the retired workspace-mode flip, the panel is more than files.
+   */
+  readonly closeEditor: (entryId: string, path: string) => void;
+  /**
+   * Open (or focus) the plan document tab and expand the panel. The tab is
+   * **pinned**, never the recyclable preview slot — file browsing must not
+   * evict the plan — and it activates, replacing the focused tab: the plan is
+   * the deliverable being reviewed. Fired by the thread cards' "Open plan"
+   * (the live `PlanStreamingCard` and the settled `PlanArtifactCard`), the
+   * Artifacts facet's `plan.md`, and the new-plan auto-open — which triggers
+   * both when a plan STARTS STREAMING and when it publishes (see `planKey`).
+   */
+  readonly openPlanDocument: () => void;
+  /**
+   * Report the current thread-item selection. Called from an effect inside the
+   * panel subtree (the level that subscribes to the selection store), keeping
+   * the owner subscription-free. While the panel is open, a new selection
+   * auto-switches to the Inspect view (unless the user picked one explicitly);
+   * a collapsed panel deliberately ignores selections — Inspect has no
+   * auto-open (it must never pull the user out of the chat).
+   */
+  readonly notifySelection: (item: SelectedThreadItem | null) => void;
+}
+
+/**
+ * Create a {@link SessionPanelController} for a viewer instance.
+ */
+export function useSessionPanel({
+  phase,
+  hasChanges,
+  planKey = null,
+  defaultView = "files",
+}: UseSessionPanelOptions): SessionPanelController {
+  const editorsStore = useWorkspaceEditorsStoreRef();
+  const [isOpen, setIsOpen] = useState(false);
+  const [view, setViewState] = useState(defaultView);
+
+  // Sticky explicit pick (rail click) — auto-switching yields to it until a
+  // meaningful state change resets it. Same semantics as the retired tab FSM.
+  const userPickedViewRef = useRef(false);
+  // Render-synced mirror so imperative callbacks read the current view without
+  // re-binding on every view change.
+  const viewRef = useRef(view);
+  viewRef.current = view;
+  // Last selection reported by the panel subtree; consulted by transitions that
+  // fire at the owner level (open, phase change) where selection state is
+  // deliberately not subscribed.
+  const selectionRef = useRef<SelectedThreadItem | null>(null);
+
+  // Running⇄terminal transition → reset the sticky pick and re-derive the view.
+  // Adjust-state-during-render (the established ResizableSplit pattern) so it
+  // lands before paint without an effect.
+  const [prevPhase, setPrevPhase] = useState(phase);
+  if (phase !== prevPhase) {
+    const wasTerminal = prevPhase !== null && isTerminalPhase(prevPhase);
+    const isNowTerminal = phase !== null && isTerminalPhase(phase);
+    setPrevPhase(phase);
+    if (wasTerminal !== isNowTerminal) {
+      userPickedViewRef.current = false;
+      setViewState(selectionRef.current ? "inspect" : defaultView);
+    }
+  }
+
+  // First write-back arrived → surface Changes, but only in an open panel and
+  // never over an explicit pick. Collapsed panels signal via badges alone.
+  const [prevHasChanges, setPrevHasChanges] = useState(hasChanges);
+  if (hasChanges !== prevHasChanges) {
+    setPrevHasChanges(hasChanges);
+    if (hasChanges && isOpen && !userPickedViewRef.current) {
+      setViewState("changes");
+    }
+  }
+
+  const openPlanDocument = useCallback(() => {
+    editorsStore.openPinned(PLAN_DOCUMENT_ENTRY_ID, PLAN_DOCUMENT_PATH);
+    setIsOpen(true);
+  }, [editorsStore]);
+
+  // A new plan arrived (first plan, or a refinement superseding it) → open the
+  // plan document tab, expanding a collapsed panel (see the planKey option doc
+  // for why this one trigger may open the panel). An effect, NOT the
+  // render-adjust idiom the phase/changes triggers use: those set this
+  // component's own state, which the idiom permits — this one mutates the
+  // external editors store (notifying subscribers), which is illegal during
+  // render. The ref (not effect-less prev-state) swallows the identity present
+  // at mount: loading a session with an old plan never hijacks the layout.
+  const prevPlanKeyRef = useRef(planKey);
+  useEffect(() => {
+    if (planKey === prevPlanKeyRef.current) return;
+    prevPlanKeyRef.current = planKey;
+    if (planKey !== null) {
+      openPlanDocument();
+    }
+  }, [planKey, openPlanDocument]);
+
+  const openPanel = useCallback(() => {
+    setIsOpen(true);
+    // Re-derive the auto view on entry: a selection made while collapsed
+    // surfaces as Inspect now (the collapsed panel ignored it by design).
+    if (!userPickedViewRef.current && selectionRef.current) {
+      setViewState("inspect");
+    }
+  }, []);
+
+  const closePanel = useCallback(() => setIsOpen(false), []);
+
+  const setView = useCallback((viewId: string) => {
+    userPickedViewRef.current = true;
+    setViewState(viewId);
+  }, []);
+
+  const openFile = useCallback(
+    (entryId: string, path: string, options?: OpenFileOptions) => {
+      editorsStore.openPreview(entryId, path, options);
+      setIsOpen(true);
+    },
+    [editorsStore],
+  );
+
+  const activateEditor = useCallback(
+    (entryId: string, path: string) => editorsStore.activate(entryId, path),
+    [editorsStore],
+  );
+
+  const pinEditor = useCallback(
+    (entryId: string, path: string) => editorsStore.pin(entryId, path),
+    [editorsStore],
+  );
+
+  const closeEditor = useCallback(
+    (entryId: string, path: string) => editorsStore.close(entryId, path),
+    [editorsStore],
+  );
+
+  const notifySelection = useCallback(
+    (item: SelectedThreadItem | null) => {
+      if (item === selectionRef.current) return;
+      selectionRef.current = item;
+      if (item) {
+        if (isOpen && !userPickedViewRef.current) setViewState("inspect");
+      } else if (viewRef.current === "inspect") {
+        // Selection cleared: leave Inspect (its content is gone) and unstick,
+        // returning to the panel's home view.
+        userPickedViewRef.current = false;
+        setViewState(defaultView);
+      }
+    },
+    [isOpen, defaultView],
+  );
+
+  return useMemo(
+    () => ({
+      editorsStore,
+      isOpen,
+      view,
+      openPanel,
+      closePanel,
+      setView,
+      openFile,
+      activateEditor,
+      pinEditor,
+      closeEditor,
+      openPlanDocument,
+      notifySelection,
+    }),
+    [
+      editorsStore,
+      isOpen,
+      view,
+      openPanel,
+      closePanel,
+      setView,
+      openFile,
+      activateEditor,
+      pinEditor,
+      closeEditor,
+      openPlanDocument,
+      notifySelection,
+    ],
+  );
+}