sessions

Before Making Any Changes

MANDATORY: Before writing or modifying any code in src/vs/sessions/, you must read these documents:

1. .github/instructions/coding-guidelines.instructions.md — Naming conventions, code style, string localization, disposable management, and DI patterns.
2. .github/instructions/source-code-organization.instructions.md — Layers, target environments, dependency injection, and folder structure conventions.

Then read the relevant spec for the area you are changing (see table below). If you modify the implementation, you must update the corresponding spec to keep it in sync.

Specification Documents

Common Pitfalls

• Keep workspace fallback discovery out of the picker UI class: provider-session subscriptions, ranking, deduplication, and existence checks belong in a focused helper such as SessionWorkspaceFallback. The picker should only enforce source priority, reject stale async results, and publish the selected workspace.

• Paired experiment treatments must resolve atomically: when a prompt and its editable placeholder are separate treatment values, use them only when both are non-empty; otherwise use both defaults so copy from different variants is never mixed. The prompt may omit the placeholder token entirely, in which case it is used literally and placeholder highlighting is simply absent.

• Onboarding variations share structural steps and vary only their run step: keep one scenario for workspace selection, then resolve the experiment/developer variation when the run step executes. Personalized GitHub prompts use existing authentication silently, stay within a bounded cancellable lookup, verify that the selected draft workspace is still current, and fall back to the default prompt without surfacing an error.

• Prompt-option headings and cards are one visual surface: group them with one enclosing border on the session surface; filling the entire group with the chat-input background makes it compete with the input, so reserve that fill for the cards. In each card, keep the icon and title on the first row, let supporting text span from the card's leading edge beneath the icon, and balance top/bottom padding so short copy does not leave a hollow corner.

• GitHub prompt-option numbers belong with the action title: render labels such as "Tackle issue #123" or "Fix CI #456" on the first row and reserve the second row for the issue/PR title. This preserves the scarce full-width line for descriptive repository content.

• Prompt-option selection has two generated input forms: the selected option stays switchable while the input is empty, exactly matches its full prompt, or exactly matches that prompt after its editable placeholder was activated and removed; every other edit disables the cards. Animate only the first insertion, replace later selections immediately, focus the input on activation, and use the card foreground for selected borders rather than conflating selection with the blue focus color.

• Repository prompt options follow the draft workspace: keep a contribution-owned watcher after the onboarding run step completes. A workspace change clears stale cards immediately, shows loading skeletons, cancels the old lookup, and resolves a fresh bounded option set for the replacement draft; completed candidates from a timed-out lookup remain available only when their repository context is still current.

• Prompt-option disabled presentation must not reuse Button's shared .disabled opacity: the base rule is !important, so component-specific selected/disabled opacity cannot win without another forbidden override. Keep cards focusable, expose aria-disabled, gate activation in the component, and use a component-owned state class; gate skeleton animation with .monaco-reduce-motion so the effective workbench.reduceMotion setting wins over the OS media query.

• Ellipsized prompt-option copy needs an explicit full-content hover: register an IHoverService managed hover on every card and include both the complete action title and complete supporting text. Do not rely on clipped DOM text or a native title tooltip; GitHub titles routinely exceed the card width.

• Three prompt options must fill every row: render three equal growing cards on one row when space allows. At the two-column breakpoint keep flex-grow enabled so the third card occupies the full wrapped row instead of leaving an empty column.

• GitHub prompt-option numbers are secondary title metadata: model the issue/PR number separately from the action title, render it beside the title using the same muted color as the second line, and combine both only for ARIA and full-content hovers. Do not parse or color substrings inside one title string.

• Agent-host onboarding readiness comes from advertised session types, not provider registration: an agent-host provider exists before its root state connects, while its sessionTypes stay empty. Gate tours that need a usable host on a context key derived from any local-agent-host/agenthost-* provider exposing a session type, and update it from ISessionsManagementService.onDidChangeSessionTypes.

• Diagnostic log text is not a unit-test contract: add consistently prefixed, actionable logs, but do not add tests that assert log messages or levels. Validate the underlying behavior and keep diagnostics free to evolve.

• Shared visual-module gates must not activate broader layout contracts: the Agents window may opt into shared editor-tab styles through a tab-specific root class, but must not apply the broad style-override class unless it also loads every matching Modern UI layout module. Keep shared tab runtime metrics aware of both gates, and preserve structural behavior such as a sticky add-tab action when removing a Sessions-owned stylesheet. Since the Agents workbench is always modern, chat-tab presentation belongs in the owning chatCompositeBar.css, scoped through .session-chat-tabs-bar and chat-specific classes while consuming shared state tokens; do not add Sessions selectors to or rewrite the shared editor stylesheet.

• Minimum-size activation across the Sessions/Editor split must be symmetric and layout-aware: when either part is at minimum width, pointer or keyboard activation expands it by shrinking its sibling to minimum width. In single-pane layout, the Editor grid node's effective minimum includes the visible docked Auxiliary Bar width; using editorPartView.minimumWidth alone collapses Details.

• Do not inject ISessionsService into editor-part construction: the sessions service depends on editor parts through the sessions-part graph, so injecting it into SinglePaneMainEditorPart causes recursive service instantiation during startup. Prefer lower-level services such as ILabelService when the editor only needs resource presentation.

• Workspace-folder labels must distinguish physical paths from repository identity: a worktree URI basename is the worktree directory, not the repository name. Route breadcrumb and workspace-projection labels through the delayed IWorkspaceFolderLabelService; the Agents implementation may read ISessionsService.activeSession because BreadcrumbsModel is created from BreadcrumbsControl.update() after editor-part construction, but never inject ISessionsService into SinglePaneMainEditorPart itself. Breadcrumbs omit a workspace root whenever only one folder exists in any VS Code window; folder changes rebuild the model and recompute labels.

• Session repository labels come from ISessionFolder.name, not the repository URI basename: providers may supply a richer display identity such as org/repo. Use the session folder name for plain and verbose labels, and use URI basenames only as the final no-session fallback.

• Breadcrumb item equality must include presentation overrides: BreadcrumbsWidget.setItems retains equal prefix items, so a custom FileElement.label must participate in equality. Otherwise folder or session-label changes for the same URI update the model but leave stale DOM text.

• Animation performance must preserve perceptual smoothness: reducing a continuous title shimmer to 10 stepped updates per second makes the sweep visibly choppy even if paint counts improve. Use a smooth baseline such as 30 updates per second, then measure the remaining performance win; do not optimize decorative motion by callback counts alone.

• Pet placement must align the visible sprite, not only its absolute-positioning box: anchoring the button at bottom: 100% leaves the pet visually detached because the input stack has top padding and transient confirmation/question surfaces add their own top margin. Keep the host on the complete stack and derive the optical offset from the actual input-to-host inset, capped at the confirmation/question alignment; one fixed deeper offset makes the bare input look overlapped.

• Keep only the rendering pet's speech bubble inside its input bounds without turning the pet around: the speech sprite's visible pixels overhang the button on the right, so dragging the rendering pet to the input's right edge can clip the ellipsis. Move the mirrored bubble fully to the pet's left with only its tail touching; do not center it over the pet, and do not apply the special treatment to yapping or any other state.

• Do not conflate custom-agent selection with Agent Host execution mode: chat.modeChange describes workbench mode/custom-agent picker selections, while interactive, plan, and autopilot are Agent Host execution modes and belong in agentHost.executionModeChanged. Preserve the SDK-native mode event as a peer rather than reshaping either axis into the other.

• Picker telemetry must use the scoped session and active chat: Agents Window action view items can belong to a non-active visible session or peer chat. Resolve previous selection and request counts from scoped ISessionContext.session.activeChat, never a window-global picker model or parent session resource.

• Regrouping already-visible picker entries as enrichment arrives: grouped async pickers must append groups in their final order rather than initially showing fallback groups and moving entries later. Fetch the source set once, run small group-membership queries in parallel, then append each completed group in display order.

• Viewer-group PR results and paged catalog results are one loaded set: search, deduplication, and re-rendering must use their union. Replacing picker items from catalog pages alone can make an already-visible matching review/assignment PR disappear.

• Folder isolation is not worktree isolation: isolationMode: 'workspace' means the ordinary folder mode and must not require supportsWorktreeConfiguration. Gate provider selection only for actual worktree settings.

• GitHub fork PR branches are not base-repository branches: use the base repository's checkoutable refs/pull/<number>/head ref (or equivalent head-repository identity/commit), never fetch the unqualified fork branch name from origin.

• PR-session exclusion must understand checkout refs: after using refs/pull/<number>/head, older or partially hydrated sessions may only expose origin/pull/<number>/head as their upstream. Recover the PR number from that ref instead of comparing it only with the source branch name.

• Hidden queued requests stay hidden while pending: propagate transcript visibility onto the pending request model and filter hidden pending rows before adding queue dividers.

• Creating a custom materialization path for a hidden bootstrap turn: use ISessionsManagementService.createAndSendNewChatRequest with the normal session options (including worktreeBranchTrack) and mark the bootstrap request/response hidden from the transcript. Keep the turn in durable model history instead of inventing a second session-creation lifecycle.

• Showing local-worktree actions on cloud-only repository headers: a GitHub-backed section is not necessarily a usable checkout, while session-type capabilities register asynchronously and file-only checks incorrectly exclude remote-host workspaces. Hide the action only for github-remote-file cloud sections, resolve within the originating section, and enforce provider capability when creation starts.

• Reading observable repository metadata once while rendering a section header: local workspace and GitHub metadata can hydrate after the tree template is created, leaving scoped menu context keys permanently false. Bind repository-derived header keys in an element-scoped autorun and clear it whenever the recycled template changes elements.

• Requiring GitHub identity and a usable checkout on the same session folder: mixed workspace sections can carry repository identity on a cloud session while a separate local/remote-host session carries the checkout. Combine identity and non-cloud workspace presence at section scope, then resolve the non-cloud folder from that originating section.

• Hiding repository actions when optional gitHubInfo is absent: some local providers intentionally leave gitHubInfo undefined even for GitHub clones. Gate only on a non-cloud workspace, then resolve identity lazily from session metadata or the checkout's ordered Git remotes when the action runs.

• Awaiting repository discovery before showing a picker: opening an unscanned checkout can take several seconds and makes the toolbar action appear inert. Show the picker immediately with a localized disabled/busy state, await repository/remotes hydration via observables, and cancel that wait when the picker closes.

• Steering visible input into a hidden bootstrap turn: tools and confirmations produced after steering still belong to the hidden response, leaving the session in Needs Input without an actionable transcript row. Keep hidden bootstrap prompts tool-free and convert steering submissions to queued messages while the active request is hidden.

• Rejecting a headless worktree create before late session types register: local Agent Host types can arrive after repository and PR selection, so a synchronous capability check produces a false "no provider" error. Keep the initiating picker busy and await onDidChangeSessionTypes without a timeout, canceling from the picker lifecycle.

• Opening a provisional chat with a filtered bootstrap and no visible state: the chat looks empty even though model loading/materialization is active. Show a quiet, accessible transcript-level readiness status driven by model/request observables, and remove it deterministically when the hidden bootstrap completes or visible content appears.

• Mirroring a child chat widget's model in the owning view: the view already owns the load reference while ChatWidget owns the active view model; a second model observable can drift during clear/rebind races. Derive view-only state from ChatWidget.onDidChangeViewModel and widget.viewModel.model, while retaining only the disposable model reference needed for lifetime ownership.

• Exposing a chat widget's internal transcript element for caller-owned markup: raw DOM access couples consumers to private structure and bypasses widget visibility/layout invariants. Add a semantic widget operation such as setTranscriptProgress(...) and keep creation, accessibility, and visibility state inside the widget.

• Keeping bootstrap context in a view-only side channel: context needed by the next request must use the normal attachment pipeline so it reaches provider history and survives restore. Attach it to the hidden bootstrap with _meta describing its transcript presentation, mirror it through a semantic widget API, and synchronously move the same entry into the first visible request before context capture.

• A sash element's left/top is the hit-area edge, not the split boundary: SplitView.getSashPosition returns the exact boundary after the preceding view, then Sash.layout subtracts half the sash size so the draggable element is centered on that boundary. Align the Sessions/Editor and bottom-Panel grid sash hit areas to agents.layout.floatingPanelGap; do not apply that token to independent geometry such as the Auxiliary Bar's leading padding.

• Wrong menu IDs: Never use MenuId.* from vs/platform/actions for Agents window UI. Always use Menus.* from browser/menus.ts.

• Editor-group header existence must not depend on an editor-provided scope: the group-level showHeader option enables both header actions and header-hosted breadcrumbs; each menu item gates itself with an active-editor when clause. An editor's optional scopedInstantiationService property only supplies context for evaluating those clauses, and breadcrumbs compose into the same fixed-height header row rather than creating a second persistent slot.

• The empty Files breadcrumb belongs to the editor area, not the docked detail: expose the session working directory as the empty Files input's breadcrumb resource only while the editor area is visible. A detail-only layout may keep header actions visible, but it must not show a root breadcrumb for hidden editor content; preserve the underlying resource separately for serialization and refresh breadcrumbs from the editor-part visibility signal.

• Pass the complete session workspace to the empty Files input, not a preselected folder URI: the input currently derives the first mounted working directory as its breadcrumb resource at one documented fallback point. A complete multi-root design can then change that input-owned decision to a workspace-level breadcrumb that identifies the workspace and exposes all roots, without rewiring every caller.

• A superseded managed-tab reconcile must not publish input state after an await: foreign-editor cleanup can yield while a newer session queues a successor reconcile. Check the reconcile generation immediately after cleanup and before updating the retained Files input's workspace, so only the current reconcile can publish breadcrumbs.

• Editor-header DOM must mirror its visual groups: breadcrumbs are a direct child of the header and a sibling of one actions container; that actions container directly owns the primary and secondary action hosts. Create the actions container and its hosts inside the showHeader construction branch, then attach it after breadcrumbs so ownership and DOM order stay explicit.

• Editor-header state belongs to the owned nodes and widgets, not their parent or CSS marker classes: do not add placement/state classes to the title parent, branch layout on the showHeader option after construction, or infer action presence from has-no-actions. Use the created header element to distinguish placement and MenuWorkbenchToolBar.getItemsLength() to derive visibility; the toolbar may still set its internal compatibility class, but header logic and styling must not depend on it.

• Secondary editor-header actions need a structural trailing column: custom secondary view items can stretch their host, so margin-left: auto plus content-sized flex is not sufficient. Use an actions grid with a flexible leading column and explicit secondary/separator/layout columns so secondary-only states remain trailing regardless of child sizing.

• Breadcrumbs and editor-header actions share an edge, not a parent gap: do not add column-gap to the header row; it creates a visible hole between the flexed breadcrumb box and actions box. Breadcrumb content owns its trailing breathing room, while the two sibling containers remain contiguous.

• Header actions must not retain an empty leading grid track beside breadcrumbs: when breadcrumbs are visible, make the actions grid content-sized with auto columns; otherwise its flexible primary column becomes a visible hole inside the actions element. Only use the full-width 1fr primary column when breadcrumbs are absent, where it keeps primary actions left-anchored and secondary/layout actions trailing.

• Header breadcrumb layout measures the control, not its padded wrapper: .breadcrumbs-below-tabs has Sessions-owned left padding, and clientWidth includes that padding. Pass breadcrumbsControl.domNode.clientWidth to BreadcrumbsControl.layout() so the widget receives its actual usable width and does not overrun or clip its trailing scroll range.

• Header-hosted breadcrumbs inherit the shared header background: the breadcrumb widget generates a light-theme background on its inner .monaco-breadcrumbs surface, which contrasts with the editor-header tab background inherited by sibling actions. Override both the control and inner widget surface to transparent in the Sessions-scoped header breadcrumb stylesheet so the entire row uses one theme-owned surface color.

• Single-tab titles and the Sessions header are separate, aligned rows: SingleEditorTabsControl renders directly into the flex title parent, unlike the multi-tab control's nested strip. In the single-pane layout, allow that parent to wrap, give EditorHeaderControl a full-row flex basis and the bottom separator, align the title label to the header content inset, and order editor actions → Add Tab toolbar (with the toolbar's trailingSeparator) → layout actions. Do not hand-style a sibling separator. Whenever showHeader is enabled, breadcrumbs live only in that header for every tab mode; do not retain the single-title inline breadcrumb. Since other tabs are hidden, Add Tab shows every supported editor type even when already open; multi-tab mode keeps the missing-tab filter.

• A single-tab title must not repeat the header breadcrumb as its description: when showHeader moves breadcrumb ownership to EditorHeaderControl, render only the editor name in SingleEditorTabsControl. Falling back to editor.getDescription(...) duplicates the same path above the breadcrumb row even though only one breadcrumb widget exists.

• Header breadcrumb ownership must not alter normal VS Code single-tab mode: EditorHeaderControl creates the single-tab breadcrumb only when showHeader is explicitly enabled. Without a header, preserve the existing SingleEditorTabsControl inline breadcrumb and do not create a second control in the shared title parent.

• The single-pane Agents editor supports only single or multiple tabs: while workbench.editor.showTabs is 'none', hold a Sessions-owned enforcePartOptions({ showTabs: 'single' }) disposable; clear it for every other value. Do not add a shared editor-part normalization hook or force one mode unconditionally; explicit single and multiple choices, including live updates, must remain respected.

• Auxiliary-Bar-only composition always uses multiple tabs: when the docked Auxiliary Bar is visible and the editor area is hidden, the Sessions-owned tab override enforces multiple regardless of the configured mode. Recompute the override from both relevant part-visibility events; when the editor returns, restore the configured single/multiple behavior (or the none → single fallback).

• Hidden header widgets must collapse their parent box: hiding only an inner control leaves the stable parent with its previous inline width, which can push sibling header actions to the right. Mirror visibility onto the parent container and define the common row height on the shared header, not on one child widget, so Changes actions and file breadcrumbs align without stale geometry.

• An empty editor-group header must collapse completely: keep the stable header content hidden by default and show it only when breadcrumbs are visible or a primary/secondary menu host has actions. Hiding only the children can leave the header border or reserved height visible as an empty row.

• Title content spans the full editor-group width: breadcrumbs and tabs use the full group width in every layout. Only the editor pane is narrowed beside the docked detail panel; do not thread the editor content inset through EditorTitleControl.layout().

• Agents header styling must not modify shared editor CSS: keep vs/workbench editor styles byte-for-byte unchanged so normal VS Code windows cannot regress. Add an explicit header-placement class in shared DOM code, then put every visual override under a Sessions-owned stylesheet scoped to .agent-sessions-workbench.dock-detail-panel.

• Header presentation has its own control: EditorGroupView passes menuIds and showHeader to EditorTitleControl, which creates EditorHeaderControl when enabled. EditorHeaderControl owns header DOM, breadcrumbs, menu toolbars, scoped action rendering, visibility, and fixed height; EditorTitleControl owns tabs and includes the header height in its total.

• The title-owned header is a child of the title container and follows its recreate lifecycle: create it after the tabs inside EditorTitleControl.parent, include its height in the title control's layout result, and rebuild it with tabs/breadcrumbs after clearNode(parent) when editor options change. Do not make it a sibling that requires separate DOM cleanup and duplicate group layout subtraction.

• Header visibility updates distinguish creation from live changes: updateHeaderVisibility(relayout) updates DOM/state in both cases, but creation and option-driven reconstruction pass false because their caller already owns layout. Live menu-item and breadcrumb changes pass true so the parent group is explicitly relaid out.

• Durable chat source/origin references: Store only turnId in durable fork/side-chat references. Active versus historical is mutable lifecycle state that consumers must resolve against the current activeTurn and retained turns when needed; do not encode lifecycle state in the reference type.

• Selected side-chat text is an immutable snapshot, not a live range: SideChatSource.selection / ChatOrigin.selection preserve the exact text captured at side-chat creation time. Never model it as offsets into the source transcript or try to recompute it from later DOM/protocol state.

• ChatSource is fully discriminated: Fork and side-chat sources both require explicit kind plus stable top-level turnId. Do not add no-kind compatibility helpers or route by structural property presence; switch directly on source.kind.

• Sessions menu ids must live in the shared menu registry: Do not declare sessions-owned new MenuId(...) constants ad hoc inside individual parts. Add them to browser/menus.ts under Menus with discoverable SessionsEditor... names so ownership and reuse stay obvious.

• Events instead of observables: Session state must flow through IObservable, not Event. Use autorun/derived for reactive UI, not onDid* event listeners.

• Importing from providers: Non-provider contrib/* code must never import from contrib/providers/*. Extract shared interfaces to services/ or common/.

• IAgentSessionsService in shared code: IAgentSessionsService (vs/workbench/contrib/chat/browser/agentSessions/agentSessionsService) is a Copilot-provider internal and may be imported only by the Copilot chat sessions provider (contrib/providers/copilotChatSessions/). Shared sessions code (core/services/non-provider contribs, e.g. the sessions list or visible-sessions grid) must stay provider-agnostic and go through ISession/ISessionsManagementService — never reach into model.observeSession(...) etc. for lazy loading. This is enforced by an ESLint no-restricted-imports ban scoped to src/vs/sessions/** (Copilot provider exempted).

• Missing entry point import: New contribution files must be imported in the appropriate sessions.*.main.ts entry point to be loaded (for example sessions.common.main.ts, sessions.desktop.main.ts, sessions.web.main.ts, or sessions.web.main.internal.ts).

• Modifying workbench code: Prefer extending/wrapping workbench classes in the sessions layer over modifying shared workbench components.

• Do not repeat subagent identity beside the open-chat pill: The subagent pill's title is the complete inline affordance. Do not render the agent name or a generic "Subagent" phrase before it; that duplicates identity and adds visual noise.

• Subagent model metadata is differential inline, but complete in the hover: Show the subagent's model beside the pill by default and hide it only when it concretely matches the parent chat's selected model. Compare canonical ids, registered display names, and the parent input's selected-model metadata (active turns may not yet expose resolved response metadata). Keep the unfiltered subagent model in the hover/ARIA label regardless of inline visibility; if the parent model is unresolved, still show it inline because no match can be established.

• Optional metadata owns its separator: Keep separators such as · on the conditional metadata element and create that element hidden. An empty optional label must never leave punctuation behind while its reactive visibility is still resolving.

• Live numeric labels must not jitter: Apply font-variant-numeric: tabular-nums with font-feature-settings: "tnum" as a fallback to elapsed-time and other numeric labels that update in place.

• Collapsed work summaries must quantify what they hide: Prefer outcome-oriented copy such as "Completed 6 steps in 2m" over vague elapsed-only text such as "Worked for a few minutes." Count the visible items placed inside the disclosure so the summary matches what expanding it reveals.

• Created-session result pills belong with the final response, not the collapsed work steps: A completed create_session / create_chat pill is a durable outcome and navigation affordance. Render it only once the response completes and order it after the final response markdown, so it stays visible beside the completed-turn adjuncts without being repositioned while focused.

• Logical final markdown is not necessarily rendered final markdown: With incremental rendering, response completion accelerates the buffer but does not synchronously drain it to the DOM. Delay completed-work disclosure and bottom-summary placement until the final markdown part reports that its morpher has drained, then retry from that signal.

• Custom action proxies must propagate owner-observed state: When an action view wraps a menu action in a proxy, state that controls surrounding UI (such as enabled/available) must also be written to the original menu action observed by the owner. Re-subscribe on IActionViewItemService.onDidChange for late factory registration, but do not assume the replacement proxy's state automatically reaches the menu action.

• Editor feedback glyph placement: Use Monaco's lineNumberClassName when the feedback affordance should replace the number only while its line is hovered; it eliminates a dedicated glyph lane while preserving the number at rest. Style the line-number pseudo-element as the full feedback control, including its themed hover background, so its visual and click target match.

• Line-number decoration tooltips belong in Monaco decoration options: A lineNumberClassName node is regenerated as the editor renders and scrolls, so DOM-managed hovers can silently attach to a stale or never-decorated element. Set the localized lineNumberHoverMessage with the same decoration instead; Monaco's glyph hover controller follows the rendered line-number lifecycle.

• Compact multi-diff control alignment: The file-header twistie, unchanged-region expand control, and fold control form one visual column in the Agents editor. Remove the header content's left padding and use the same small inset for both unchanged-region controls; do not let the shared multi-diff defaults leave each control at a separate horizontal offset.

• Embedded multi-diff gutters need a shared minimum width: Each embedded editor otherwise sizes line numbers from its own largest line number, causing the content and nearby feedback glyph to appear to drift between file entries. Set a common lineNumbersMinChars width for the compact multi-diff; it remains stable through three-digit line numbers and grows only when a file exceeds that reserved capacity.

• Editor-content overlays must anchor to the inset pane, not the full editor group: In single-pane mode the editor group spans both the editor and docked detail panel, while EditorGroupView.editorPaneContainer bounds only the editor content. Mount submit/navigation overlays to that pane container so their bottom-right position stays inside the diff when the detail panel is visible or resized.

• Timeouts as fixes: Never use setTimeout/disposableTimeout/arbitrary delays to fix bugs or implement behaviour. They are race-prone guesses that mask the real ordering/state problem. Drive logic off deterministic signals instead — observables (autorun/derived), explicit events (onDidChange*), lifecycle phases, or awaiting the actual async operation.

• The prompt timeline dock treats the bottom as the latest prompt and pairs both hover directions: when the transcript is fully scrolled down, resolve the final prompt directly rather than scanning every prompt's top offset. Hovering either a dot or its prompt row must preview both elements; when the dots are capped, map the row to the nearest sampled dot.

• Sticky prompt navigation must match the rail/title reveal: Previous/Next and the sticky title must all reveal the prompt (request) row aligned to the top via the shared reveal(requestId) — the same path the dock/ruler rail uses. Do not align the following response to keep the header pinned, and do not add a "navigation pin" that forces the header to stay visible after a jump: the header is a top:0 overlay, so it would cover the freshly top-aligned prompt (the prompt shows only a sliver). Let the header follow scroll tracking (it hides once the prompt is at the top), consistent with the dock. Use the chat request-bubble hover background (--vscode-chat-requestBubbleHoverBackground, toolbar hover as fallback), composited over the opaque panel base, for the sticky title affordance rather than an underline.

• Sticky prompt header transition is a label roll, not a moving band: on prompt change the label text rolls (WAAPI slide+fade of absolutely-positioned line elements inside an overflow:hidden clip viewport), while the opaque band stays fixed. Do NOT translate the whole band to get an Explorer-style push-off: the band would move above the transcript top (its container .interactive-session is overflow:visible, so it'd overlap the session header) and clipping it would cut the band's soft drop-shadow. The roll gives the "header gives way to the next" feel with none of that risk. Gate the roll on the header already being visible (snap on first appearance/jumps) and honor prefers-reduced-motion.

• Sticky prompt header must mirror the session header's box model, not the message column: the band lives in a two-level structure — an outer full-width .prompt-timeline-sticky (positioning + reveal only), a .prompt-timeline-sticky-content centered host (max-width: 950px; margin: 0 auto; padding: 0 10px, matching .session-view-centered-content + .chat-composite-bar.session-header-bar's 10px side padding), and an inner .prompt-timeline-sticky-band (flex: 1) that carries the background/border/shadow (mirroring .chat-composite-bar-header). This makes the band's background align exactly with the session header's bottom-border line above it. Do NOT paint the background on the full-width outer (bleeds past the header and over the scrollbar gutter — a ~1px right-edge "bump") or on the 950 message column (20px wider than the header, since the header is inset 10px). The band's padding-left: 22px (16px icon + 6px gap) reproduces the header's status-icon column so the prompt text lines up with the title and the 32px-inset prompts below.

• Grid onDidChange is not a sash-drag signal: the workbench SerializableGrid/GridView onDidChange fires for size changes and view add/remove, but not internal splitview sash drags. If logic must react to a part node being resized by a sash, route it through that part's layout(width, ...) callback, which receives the in-progress node width.

• Docked detail collapse must use the raw sash width before clamping: the docked auxiliary bar keeps a minimum visible width, so checking the clamped width can never detect a drag-to-zero collapse. Decide collapse from the raw requested sash width, then route the hide through setPartHidden(AUXILIARYBAR_PART) so context keys and per-session capture stay in sync.

• Stashed state read back later (side-channels): Never stash a value on a service during one method call and read it back from a separate query later, assuming it is still valid (e.g. a Set/flag set in openSession and consumed by a shouldX() pull-API). This is fragile temporal coupling. Instead, make it reactive state that is set atomically together with its source of truth and consumed reactively. Example: per-activation intent like "open in background / preserve focus" is exposed as an IObservable set in the same transaction as activeSession (via a single internal setter so it can never go stale), and read with .read(reader) in the consumer's autorun — never via a consume-once getter.

• Provider-owned model/mode selection belongs in the loaded chat model, with draft persistence driven by debounce: For AHP-backed chats, setModel / setAgent must push the selection into the loaded IChatModel.inputModel (like _updateChatSessionState) and let the draft-sync debounce emit chat/draftChanged. Do not immediately dispatch a model/agent-only draft from the provider, because it can overwrite unsaved typed text before the debounced full input-state draft is persisted.

• Blocking on a "pending/waiting" state instead of creating + upgrading: When an entity (e.g. a draft session) depends on something that registers asynchronously, don't withhold creation behind a pending/waiting state. Prefer creating immediately with the best available data, then replace/upgrade it once the awaited dependency arrives (driven by an onDidChange*/observable signal), cancelling the upgrade if the user changes the inputs meanwhile. Do not bound the upgrade with a timeout or even a lifecycle milestone like LifecyclePhase.Eventually — an agent host connects lazily and can surface its session types arbitrarily late, which would lock in the wrong fallback. Let the upgrade listener live for the consumer's lifetime instead.

• Over-commenting: Don't write long explanatory comments narrating what the code does or justifying ordinary patterns. Hard rules: JSDoc = 1–2 short sentences max (never enumerate every branch/feature, restate the signature, or list what the function does NOT do); inline method comments = 1 line max, only for a genuine workaround/non-obvious constraint, never to narrate the next statement. Default to no comment — if code needs a paragraph to explain, rename/extract instead. Before writing any comment longer than one line, delete it or shorten it to one line.

• Inserting/removing DOM on demand for transient UI (e.g. inline rename inputs): Don't insertBefore/appendChild+remove() a widget on the tab/row element itself when an interaction starts/ends — that churns the parent's child list and depends on event ordering during teardown. Also don't eagerly build a heavy widget (e.g. an InputBox) per row "just in case", since most rows never use it. Instead, create a stable, empty container alongside the label once, toggle its visibility via a CSS class on the row (e.g. .editing), and create the widget inside that container lazily only while editing — disposing it and emptying the container (reset(container)) when done (InputBox.dispose() does not detach its own node). Prefer the shared themed widget (InputBox + defaultInputBoxStyles) over a hand-rolled <input>.

• Collapsing distinct provider identities in pickers: Do not collapse extension-backed chat session ids (e.g. copilotcli) and agent-host ids (e.g. agent-host-copilotcli) based only on friendly names or well-known provider enums. They can coexist in the Agents window and route to different infrastructure; keep the exact session type id through selection/delegation and hide ambiguous legacy targets when an agent-host target supersedes them.

• Permission picker copy must stay provider-neutral and aligned: Reuse the same labels and descriptions across Copilot Chat and Agent Host permission pickers. Avoid provider-specific phrasing such as "Copilot uses..." when the same choice appears in the Agents window.

• Interactive tool denial must use an accepted SDK decision with feedback, not a completion outcome: In the Agent Host Copilot provider, a user choosing Skip must resolve the permission request with { kind: 'reject', feedback: '...' }. The feedback makes the SDK feed the denial back to the model and continue the turn; denied-interactively-by-user is a completion outcome that the current runtime rejects as a malformed permission-host response. Reserve a bare reject for abort, disposal, or requests that cannot be presented to the user.

• Internal Agents workspace in recent history: Collapse every internal User/agent-sessions.code-workspace variant into one canonical Agents Window entry. Recognize the reserved path across profile and worktree user-data directories, and make the single picker entry point at the current environment's Agents workspace.

• Resolving a session's provider via the create-only tracking map: On the agent host, resolve the owning provider for any per-session operation (createChat, disposeChat, sendMessage, …) through AgentService._findProviderForSession, never the raw _sessionToProvider map. That map is populated only by createSession, so a restored session (alive in the state manager after a host restart but never created in this process) is absent from it — a direct lookup throws no provider for session and silently breaks the feature (e.g. Add Chat did nothing for restored sessions while messaging worked, because messaging already used the fallback). _findProviderForSession falls back to the session URI's scheme provider, which is what makes restored sessions work.

• Dispatching per-chat side-channel actions (agent/model) to the session URI: An agent-host session can own multiple peer chats, each with its own backend conversation (CopilotAgent._chatSessions). Conversation side-channel actions like SessionAgentChanged/SessionModelChanged must be dispatched to the per-chat turn channel (_resolveTurnDispatchChannel, which carries a chatId fragment for peer chats), not session.toString(). The session URI resolves to the session's default chat (_sessions), so dispatching there silently applies the change to the wrong conversation and an additional chat never sees the agent/model swap. The host must also forward the chatChannel through agentSideEffects.handleAction → changeAgent/changeModel, which apply it to _chatSessions when present. The protocol models summary.agent/summary.model at session level only, so equality guards comparing against session summary are valid for the default chat but must be skipped for peer chats.

• Do not infer or fall back from a peer chat channel after progress was emitted: Agent progress signals for chat-scoped actions, especially tool-call readiness and permission requests, must be emitted with the exact ahp-chat://... channel that owns the tool. Do not recover by scanning active turns, remapping ChatToolCallConfirmed, or using parseDefaultChatUri(...) ?? sessionUri in AgentSideEffects; malformed/misrouted chat channels should fail loudly so the producer or dispatch path is fixed. handleToolCallConfirmed and _toolCallAgents must use the chat channel URI containing the tool call; keying by the parent session URI makes confirmations miss the pending SDK request.

• Do not synthesize default chat URIs in the workbench handler: AgentHostSessionHandler must source the upstream default chat URI from hydrated SessionState.defaultChat / SessionState.chats and store that mapping in its chat-resource-to-upstream-URI map. Calling buildDefaultChatUri(session) in the handler assumes one server URI shape and hides protocol/provider bugs; dispatch turn lifecycle and pending/input actions through the mapped upstream chat URI instead.

• Opening a subagent editor must carry the exact upstream chat channel: A fragment-only editor resource forces AgentHostSessionHandler to rediscover the child in SessionState.chats, which races catalog hydration and renders "Cannot resolve chat". Encode the exact ahp-chat://subagent/... channel in an internal query parameter, validate its chat id and owning backend session, and subscribe directly.

• Model subagents as chats, not sessions: A subagent spawned from a tool call belongs to the parent session as an additional chat with origin.kind === "tool", hidden from the chat tab strip. Do not call restoreSession for subagents; that creates _sessionStates without a matching _chatStates entry, so later chat actions hit "Action for unknown chat". Add a chat on the parent session and dispatch the subagent turn to that chat URI.

• Keep case-sensitive ids out of URI authority: URI authorities are case-insensitive, so do not place tool call ids in the ahp-chat authority. Subagent chat URIs use a stable subagent authority and put the encoded tool call id in the path; use buildSubagentChatUri(...) instead of buildChatUri(..., \subagent-${toolCallId}`)`.

• Selected custom agent must be in the SDK's customAgents, not just pluginDirectories: The Copilot SDK validates the session-start agent: option (passed to createSession/resumeSession) against the customAgents list by name only — it does NOT consult pluginDirectories. copilotSessionLauncher._buildSessionConfig deliberately omits agents from file-dir plugins from customAgents (relying on the SDK's pluginDirectories discovery to avoid duplicates), so selecting a plugin/extension-contributed agent (e.g. "Inbox") otherwise fails with Custom agent '<name>' not found. The fix (toSdkSessionCustomAgents) force-adds the resolved selected agent into customAgents while every other file-dir agent still loads via pluginDirectories. Note the agent picker offers VS Code chat modes from IChatModeService, but only plugin/extension storage agents are synced to the host (SYNCABLE_STORAGE_SOURCES); user/local agents are never synced, so _resolveAgentName returns undefined for them and no agent: is sent.

• Derive SDK custom-agent names exactly like parseAgentFile: _resolveAgentName resolves the selected agent through the plugin parser, which trims the frontmatter name (getStringValue('name')?.trim() || nameFromFile). When building the SDK customAgents list (toSdkCustomAgents), derive the name the same way (?.trim() || agent.name); reading the raw frontmatter name without trimming yields a config name that won't match the trimmed resolvedAgentName, so the SDK still rejects the session with Custom agent '<name>' not found.

• Peer chats have no server summary, so dedup side-channel dispatch against the last value sent for that chat: equality guards before dispatching SessionModelChanged/SessionAgentChanged compare against summary.model/summary.agent, which only exist for the session's default chat. For peer chats, track the last-dispatched model/agent on the AgentHostChatSession instance (auto-cleaned on dispose) and diff against that — otherwise every peer-chat turn redundantly re-dispatches (and re-resolves the agent), and an intentional "clear selection" (undefined) can't be detected.

• Scrollable transcript surfaces must use workbench scrollbars: Don't make Agents/voice transcript regions scrollable with native overflow-y: auto on the content node. Wrap transcript content in DomScrollableElement/list widgets so scrollbars match VS Code theming and remain usable in narrow auxiliary-window layouts.

• Background-sending a multi-chat composer must reset the composer before dispatching the send, not concurrently: in NewChatInSessionWidget._send, creating the replacement untitled chat (openNewChatInSession({ forceNew: true }) → provider.createNewChat) and the fire-and-forget background sendRequest both reach into shared chat-session state (acquireOrLoadSession / getOrCreateChatSession) for chats in the same group. Running them concurrently (send first, reset second) raced and left the sent chat stuck spinning with its message never dispatched, plus a second empty "New Chat" tab. Fully await the composer reset first, then fire the background send so it runs on its own.

• Chat tab order is the provider's stable creation order; don't reorder in the renderer: the agent host delivers state.chats in stable creation order (append on add, replace-in-place on update — see agentHostStateManager/the session reducer), and a genuinely new chat is appended last. The renderer's rebuild autorun (chatCompositeBar.ts) must render that order as-is. Do not partition/move in-composer Untitled chats to the end: a draft is already last, and reordering by status makes a tab jump when a draft commits out of creation order (e.g. sending the 3rd of three drafts first moved it to the front). A chat's Untitled presentation (via AdditionalChat._isNew, needed so sessionView.ts shows the composer) is independent of tab order and must not drive it. Also note _restorePeerChats (agentService.ts) must seed restored chats in getChats() order, not in Promise.all resolution order, or the catalog scrambles on reload.

• A new chat must report SessionStatus.Untitled until its first request is sent, regardless of how the provider creates it: sessionView.ts only shows the new-chat composer (which owns the Alt+Enter background-send handler) when activeChat.status === Untitled. The agent host commits a new peer chat eagerly, so its host status is Completed — surfacing the standard chat widget and breaking background send. Gate the chat's presented status on a provider-side isNew flag (AdditionalChat.markNew/markSent, set in createNewChat and cleared in sendRequest's committed-chat branch), not on the host-reported status.

• Service operations should return a result or throw, not undefined for unsupported cases: capability-gated operations like forkChatInSession must throw when the provider/session cannot perform them. Keep fallback decisions in the caller before invoking the service instead of encoding fallback as an undefined service result.

• A provisional session abandoned during commit detection must not be returned as successful: its status can remain InProgress after its lifecycle owner is disposed, so consumers waiting for a terminal status never settle. Clean up the provisional session and reject the send when commit detection times out or the connection is lost.

• Drop a fork when its turn point is unknown, don't forward it empty: in AgentService.createChat/createSession, if the requested fork turnId/turnIndex resolves to no source turns, set fork: undefined and fall through to a fresh create. Forwarding the fork with an empty turn slice makes the Copilot provider call sessions.fork with no toEventId, inheriting the entire backend conversation while the new chat UI is seeded with zero turns — an inconsistent hidden-history chat.

• Side-chat context belongs to the provider, not AgentService message mutation: AgentService records and forwards the side-chat origin, but must not synthesize a first-turn Chat attachment or strip provider-added context on restore. Each supporting provider establishes hidden backend context and removes inherited/provider-added history from the turns it returns.

• MessageAttachmentKind.Chat is generic and may reference unloaded chats: resolve chat attachments through a generic async path, enforce same-session ownership before hydration, and restore the referenced session/chat when it is absent from the state manager. Do not name this logic after side chats or assume /btw is its only producer.

• Agent capabilities are provider-specific: do not implement side chats for an agent merely because the protocol supports them. Advertise multipleChats.sideChat and run shared side-chat tests only for providers with a complete provider-owned context/restore implementation.

• User-created side chats use the standard peer-chat tab model; only tool-origin subagents stay hidden by default: a ChatOriginKind.SideChat chat is a normal user-facing peer chat, so it must flow through visibleChatTabs, the Conversations menu, pickers, and close/reopen like any other peer chat. Do not create a separate editor/detail surface for it; reserve the hidden/read-only default only for tool-origin subagents.

• /btw must bypass queue/steer, may anchor to activeTurn, and should activate the new peer chat through the normal sessions API: mark the silent slash command executeDuringRequest so the chat widget invokes it independently, validate its anchor against completed turns or the current active turn, and after creating the side chat activate it via ISessionsService.openChat(...) before sending on that chat. Provider side-chat creation must lock on the new chat, not the source send key. Wrap the first provider prompt with a succinct instruction to prefer explanation over action and avoid work unless explicitly requested; include bounded user-visible active-turn markdown when native forks omit it, then strip the private wrapper from reconstructed visible history. Never inject reasoning or tool payloads.

• A responsive-layout autorun must re-baseline (not react) to controller-driven restores, holding the flag across the async reveal: the desktop [D7] responsive sidebar hides the sessions sidebar when small + editor + aux-bar are all open. Switching sessions restores layout via two async paths — the desktop aux-bar restore (openView/openViewContainer) and the base controller's editor working-set apply (_applyWorkingSet, which reveals the editor part after an await and runs on a Sequencer microtask). Both reveal parts in a later autorun run, so an inline "same-run session changed" check only absorbs the synchronous transition and the async reveal still auto-hid the sidebar on navigation. Fix: a shared base-controller _withSessionLayoutRestore(work) epoch wraps both restore paths (the working-set wrap is the critical one for non-modal editors); the D7 autorun re-baselines _previousSpaceConstrained while _isRestoringSessionLayout is true. Also gate the constrained derivation on !multipleSessionsVisibleObs so the feature is disabled with multiple sessions visible. Never use a setTimeout to bridge the async reveal — tie the flag to the actual promise.

• A promise-tied "epoch" helper must decrement synchronously for void/sync work, only deferring for real Promises: _withSessionLayoutRestore increments a depth counter, runs work(), and decrements when done. If it always schedules the decrement on a microtask (Promise.resolve(result).finally(...)) — even when work() returns undefined (the common no-op restore, e.g. a session with no workspace) — the depth stays elevated for the entire synchronous caller/test body, so _isRestoringSessionLayout reads true forever and the consumer (D7) silently stops acting. Only defer the decrement when work() returns a thenable; for void/sync (or throwing) work, decrement in the finally.

• A quick-chat's workspace-less kind is seeded at adapter construction and only ever promoted — every path that can carry _meta must carry it: AgentHostSessionAdapter seeds its session-kind (QuickChatSessionKind vs WorkspaceSessionKind) from readSessionWorkspaceless(metadata._meta) in the constructor, and _promoteToQuickChatIfWorkspaceless (from update()/setMeta()) later flips it to a quick chat the first time an authoritative _meta says workspace-less — never back, since an absent marker means "not included", not "cleared". So the _meta.workspaceless tag must ride on every metadata path: _refreshSessions()/listSessions, the live _handleSessionAdded(summary) notification, and both ends of the AHP root/listSessions round-trip (protocolServerHandler.ts and remoteAgentHostProtocolClient.ts build their wire items field-by-field, and satisfies SessionSummary does not catch a dropped optional field — this is exactly how the bug shipped twice). Dropping it makes a committed quick chat render under a section header labelled with its raw session UUID, leaking <userHome>/.copilot/chats/<id> as a workspace (breaking the archive-on-delete fallback, list badges, changes/files) until a later _meta heals it. _persistCache must overlay the adapter's live isQuickChat rather than the _metaByRawId snapshot, or the next updateAdapter silently strips the marker from the startup cache. On the host, AgentService.listSessions() overlays _meta.workspaceless onto the provider listing from the persisted agentHost.workspaceless session-database key (AH_META_WORKSPACELESS_DB_KEY) (the providers themselves, e.g. CopilotAgent.listSessions(), do not emit it) so restored sessions carry the tag once the state-manager live summary is gone. The host still keeps the tag on both the summary _meta and SessionState._meta (createSessionState(summary) copies it) so the channels stay consistent. Note the provider tests cannot catch a wire-level drop — MockAgentHostService.listSessions returns stored IAgentSessionMetadata verbatim, bypassing both mappers — so wire regressions need tests at the protocol layer.

• Don't infer "quick chat" from workspace === undefined: a session's workspace observable is undefined for genuine quick chats but also transiently/edge-case for workspace-bound sessions, so keying quick-chat UI (context keys, list grouping) on it is imprecise. Expose the intent explicitly via the optional ISession.isQuickChat: IObservable<boolean> (only quick-chat-capable providers set it; absent ⇒ false). The agent-host adapter exposes it as a monotonic observable seeded from readSessionWorkspaceless(metadata._meta) at construction and promoted by later authoritative _meta; non-quick-chat providers omit it. Consume it through isQuickChatSession(session) / session.isQuickChat?.read(reader) ?? false.

• Workspace-less is inferred from absent workingDirectory — exclude forks from that inference: in CopilotAgent.createSession, isWorkspaceless must be !sessionConfig.fork && !sessionConfig.workingDirectory. A fork that arrives without an explicit workingDirectory should inherit the source session's context, not be tagged agentHost.workspaceless and dropped into a scratch dir + quick-chat system prompt.

• On a failed quick-chat create, don't activate an unrelated draft: SessionsService.openQuickChat must, on createQuickChat throwing, log and return undefined without falling back to _activate(newSession.get()) — that observable can hold a workspace-bound draft from a different call site, so activating it is surprising. Return the activated IActiveSession from _activate/openQuickChat (setActive is synchronous and yields the wrapper) and have the caller focus that exact value, rather than re-reading activeSession.get() afterwards.

• Hide an aux-bar view CONTAINER via hideIfEmpty: true + a view when, not a container when: IViewContainerDescriptor has no when property (only IViewDescriptor does). To conditionally hide a whole container (its tab/title) — e.g. the Agents-window Changes/Files containers for workspace-less sessions — put the context-key when on the inner view(s) and set hideIfEmpty: true on the container. Container visibility is hideIfEmpty && activeViewDescriptors.length === 0 (viewsService.updateViewContainerEnablementContextKey), and activeViewDescriptors already respects each view's when, so the container hides reactively when all its views' when go false.

• Don't gate "is this a quick chat?" routing on isCreated && isQuickChat: a quick-chat draft is Untitled, so isCreated (= status !== Untitled, visibleSessions.ts) is false — yet it is still a quick chat. Gating quick-chat routing on isCreated && isQuickChat (e.g. the "New" action) makes a draft fall through to the workspace path (scratch-dir composer, no session-type picker, "No models available"). Route on isQuickChat alone so drafts and committed quick chats behave identically; use isCreated only when you genuinely need to distinguish a committed session from an in-composer draft.

• Cmd+N in the Agents window is a new-session gesture only — don't fold quick-chat/peer-chat creation into it: session creation (Cmd+N, NewChatInSessionsWindowAction/workbench.action.sessions.newChat → always openNewSession), quick-chat creation (Chats-section "+", Cmd+K Cmd+N, NewQuickChatAction → openQuickChat), and peer-chat creation (chat "+", Cmd+T, AddChatToSessionAction) are three distinct keybindable actions. Keep them separate — Cmd+N must not become context-aware/mirror-route to a quick chat based on the active session's kind.

• The New action must never inherit a quick chat's folder into the workspace composer: openNewSessionFromActive seeds the new-session composer with activeSession.workspace.get()?.uri. A quick chat is workspace-less by intent, but if its workspace observable is ever non-undefined (e.g. a stale-build/coupling leak where _kind resolved to WorkspaceSessionKind because _meta.workspaceless was dropped, exposing the host's scratch ~/.copilot/chats/<id> cwd as a workspace), Cmd+N would carry that scratch dir into createNewSession → "New session in <scratch>", single/no session type, no picker, "No models available". Gate the folder inheritance on activeSession.isQuickChat so a quick chat always falls to the clean folder-picker composer regardless of any leaked workspace value.

• A reused new-session composer must re-seed its workspace draft when it swaps out of quick-chat mode: the session-type picker hides itself when it has no folder types (sessionTypePicker _folderSessionTypes.length === 0), which is the case whenever the composer has no active session (refresh(undefined) clears the types). A freshly opened new-session composer avoids this by seeding a workspace draft from the restored folder in its constructor — but the same NewChatWidget instance is reused across the quick-chat→new-session transition (sessionView.ts keeps kind==='newSession'), and Cmd+N's openNewSession discard branch only _activate(undefined), leaving the reused composer session-less → picker hidden. Fix by re-running the constructor's seed (_seedWorkspaceDraft()) from an autorun when _isQuickChatComposer flips true→false with no active session, so the reused composer matches a fresh one (folder + visible picker). Don't assume the constructor-time restore covers a reused composer.

• Every untitled-session-title fallback must be quick-chat aware: an untitled session's title observable is '', so a hardcoded localize(…, "New Session") fallback shows "New Session" even for a quick chat (whose composer says "New Chat"). Route all such fallbacks through the shared getUntitledSessionTitle(isQuickChat) helper (services/sessions/common/session.ts, boolean param so each caller controls reader-tracked .read(reader) vs .get()). There are ≥5 sites — titlebar (sessionsTitleBarWidget), session header (×2: title + rename placeholder), list-row hover (sessionHoverContent), sessions picker (sessionsActions) — keep them on the helper; never hardcode "New Session". (The Cmd+N action title stays "New Session" — that action creates a session, unrelated to a session's own title.)

• NeedsInput is still an active turn for live turn UI: agent-host tool and input confirmations intentionally transition a running chat from InProgress to NeedsInput without ending activeTurn. Live status surfaces such as the chat input pills must use isActiveSessionStatus so they do not disappear until the next output returns the chat to InProgress.

• Chat file pills classify files against the owning session, never the window-global workspace context: multiple sessions can render concurrently, so IChat.lastTurnChanges carries isOutsideWorkspace derived from that session's workspace/worktree roots, and per-response file edits carry the same metadata. AgentHostSessionAdapter owns a generic session-output cache passed to output reducers; workspace classification uses the namespaced key isOutsideWorkspace:${uri.toString()}, and workspace changes clear the cache. Keep change counts/diffs workspace-only, preview only external markdown, and open resources through chat.editorAssociations rather than invoking markdown.showPreview directly.

• Agent-host-only exclusions for built-in client tools belong in ClientToolSetsContribution, not the global tool registration: AgentHostActiveClientService.getClientTools advertises enabled members of every non-deprecated tool set, including extension-contributed sets. For vscode-general, the Agents window exposes only Tool Search; gate every other member on !IAICustomizationWorkspaceService.isSessionsWindow so editor-window Agent Host sessions and normal Copilot chat retain them.

• Non-interactive MCP authentication probes must not create dynamic authentication providers: Provider creation can prompt for manual client registration when dynamic registration is unsupported. With allowInteraction: false, only inspect existing providers and sessions; defer metadata discovery and provider creation until the user invokes the mcpAuthenticationRequired action.

• Use structured maps for the state that is actually multi-keyed, not for an incidental cache: If MCP tracking is addressed by session + server, model that source of truth directly with NKeyMap. Do not add a separate NKeyMap that merely caches serialized storage keys while leaving the real tracking state in nested or synchronized maps.

• Subagent activity rows must preserve rich tool presentation, stable height, tool identity, and protocol intent: Do not flatten markdown invocation messages into text, omit the shared tool icon, or show a raw terminal command when ToolCallBase.intention exists. Render invocation markdown with the shared chat/file-widget path and the registered/inferred compact tool icon, keep it constrained to one line within a static minimum-height slot so text, code, and file chips do not shift surrounding content, and use terminal intention before invocation-message fallback.

• Subagent reasoning preserves the last tool activity: Show "Working on it..." only during startup (before any tool is known) and while child markdown is streaming. Child reasoning must not replace the activity row; retain the most recent tool presentation, or keep the startup placeholder when no tool has run yet.

• Cross-window pending cloud tasks must be consumed only by the matching repository workspace: the source window observes the shared pending-session file before vscode.openFolder creates the target window. Keep the pending task until the Git API is initialized and pendingSession.url matches an open repository; then open the task and clear global state.

Capturing Feedback (meta-rule)

Whenever the user flags a wrong pattern, rejects an approach, or gives design/rules feedback, automatically add it as a concise pitfall/learning to this Common Pitfalls section (or the most relevant spec doc) in the same change — without being asked again. Keep each entry 1–3 sentences: the anti-pattern, why it is wrong, and the preferred pattern.

• Menu-order changes must update every registration assertion: action ordering can be covered by tests outside the action's owning contribution. Search for the previous order and command id, then update all affected expectations so focused tests do not leave the broader suite stale.

• Shared commands must delegate behavior to the layout service, not inspect a layout implementation: workbench.action.toggleAuxiliaryBar must call the semantic IWorkbenchLayoutService.toggleSecondarySideBar() operation. Do not branch on optional layout properties or concrete workbench shape in the shared action; each workbench owns how its secondary-sidebar affordance maps to visible parts.

• Definitive session deletion and temporary list eviction are different operations: deletion clears durable provenance and pending state; filtering a still-existing session only removes its visible list entry. Keep the list-removal helper side-effect-free, and let each caller explicitly update its mutation generation instead of passing an "already incremented" boolean.

• Durable user intent must never be discarded on onDidChangeSessions.removed: pins, manual sort keys, and group membership (SessionsListModelService, SessionGroupsService) are cleared only on ISessionsManagementService.onDidDeleteSession (or archive), never on the provider's removed delta. removed is an eviction, not a deletion: BaseAgentHostSessionsProvider._refreshSessions reconciles against one listing that the host aggregates across all its agents, and an agent that cannot answer yet returns [] instead of failing (CodexAgent.listSessions returns [] for a missing _githubToken, a not-yet-downloaded SDK, or a failed thread/list; ClaudeAgent.listSessions does the same). Persisting the removal turned a ~300 ms startup race into permanent loss of the user's pins and groups. Runtime-only consumers of removed (terminals, grid slots, layout) are fine as-is — only persisted state needs the delete event.

• _refreshSessions must not evict a cached session whose agent contributed no rows: a listing with zero rows for an agent means "unknown", not "empty", so scope eviction to listedAgentProviders (the set of AgentSession.provider(...) schemes actually present in the response) and compare against adapter.agentProvider. Real deletions still arrive through deleteSessions and the sessionRemoved notification; the only cost is that an agent's last session, deleted elsewhere, lingers until it lists something again.

• Keep session-list refresh filtering linear: when retention pruning needs the complete backend key set, collect those keys while filtering entries in the original loop, then reconcile last-seen/pruning afterward. Do not introduce a candidate-map/filter/map pipeline when one loop plus one reconciliation call expresses the lifecycle more clearly.

• Centralize session workspace filtering behind a semantic predicate: refresh, add-notification, and summary-update paths should call one _isSessionInWorkspace(entry)-style helper. Keep key construction, working-directory parsing, pending-local lookup, and provenance checks out of each caller so the high-level list flow stays readable and all paths apply identical rules.

• Multi-root Editor filtering belongs to durable session metadata, not a workspace memento: sessions with _meta.multiRoot.workspaceFile match a multi-root Editor window by URI identity against IWorkspace.configuration. Metadata-less sessions use containment against any current folder; do not retain a parallel workspace-scoped membership store whose lifecycle can drift from the host-owned session metadata.

• Name semantic layout operations after the user-facing surface: a shared operation must use the stable UI concept (toggleSecondarySideBar()), not the implementation term (AuxiliaryBar) that happens to back it in classic layouts. This keeps single-pane mappings clear and avoids leaking layout internals through the API.

• Semantic layout commands need matching visibility and focus semantics: when a shared command maps to a different surface, expose a semantic visibility query for its toggled state and transfer focus before hiding the currently focused mapped surface. Otherwise menu labels lie about the action and keyboard users retain focus in hidden content.

• In the single-pane workbench, the secondary side bar is the side pane: SinglePaneWorkbench.toggleSecondarySideBar() (backing workbench.action.toggleAuxiliaryBar) delegates to toggleSidePane() and isSecondarySideBarVisible() reports the side pane's visibility. The docked detail lives inside the editor part, so hiding transfers focus from either side-pane part to the sessions list. Do not add a separate editor-pane toggle operation; consolidate on toggleSidePane().

• ISession.capabilities must be observable, not a live plain getter: capabilities can hydrate/change after a session first surfaces (e.g. an agent host whose root state arrives after the session's first SessionState). A plain getter cannot be tracked by the context-key autorun (setActiveSessionContextKeys reads it inside an autorun), so supportsMultipleChats/sessionSupportsFork would stay stale, and a multi-chat catalog processed while supportsMultipleChats was still false would stay collapsed to [defaultChat]. Expose capabilities as IObservable<ISessionCapabilities> (agent host derives it from connection.rootState via observableFromEvent + derivedOpts with structuralEquals; static providers use constObservable), have consumers read .read(reader)/.get(), and re-apply the chat catalog from the last SessionState in an autorun on capability change. Do not fix this by firing _onDidChangeSessions — the active-session context autorun tracks the session's own observables, not the provider's session-list event.

• A managed/default editor tab must be re-ensured every sync, not opened once: the per-session editor working-set restore (baseSessionLayoutController [B2] _applyWorkingSet) runs on session activation and is not docked-gated, so it reinstates the session's saved editor set and will close any tab not in it (e.g. a set persisted before a new tab existed). A controller that opens a default tab once (guarded by a Set of initialized sessions) therefore loses it permanently after the restore. Ensure managed tabs (the pinned Changes tab, the default File tab) idempotently on every sync (group.editors.some(e => e instanceof X) → open if absent), exactly like the Changes tab — never with an open-once Set. Also: IEditorService.openEditor(input, group) on a typed EditorInput binds group to the options param (overload is (editor, options?, group?)); pass openEditor(input, undefined, group).

• A "keep the editor closed" rule must not react to the editor's visibility transition: the single-pane new-session rule (R1, _registerSinglePaneNewSessionRules) must drive its hide off the session + active editor, never off onDidChangePartVisibility/an editorVisibleObs. onWillOpenEditor reveals the editor before the opened file becomes the active editor, and toggling the detail panel off reveals the empty editor via setAuxiliaryBarHidden — both fire the visibility event synchronously with the active editor still stale (managed empty tab). A rule that re-runs on that transition re-hides the editor the user just asked to show (file never appears; the whole side pane vanishes on detail-toggle). Hide only when the active editor is non-real content, read the current visibility untracked when deciding to hide, and block spurious width-based reveals at the source with setSuppressDockedEditorRevealSync(true) rather than a visibility backstop. Refinement: dropping the visibility trigger entirely loses the backstop for automatic post-activation reveals (working-set restore, an editor left visible across a session switch), so the editor can appear in a fresh new-session view. Keep the visibility trigger but gate the hide on an explicit-reveal flag: the workbench records _editorRevealedExplicitly (set true only on onWillOpenEditor and the detail-toggle reveal, cleared on any hide and on the suppress false->true transition so a stale cross-session flag can't leak) and exposes isEditorRevealedExplicitly(); R1 re-hides only when the editor is visible and the reveal was not explicit.

• When the docked editor is hidden while the detail stays visible, clear the sidebar-grow snapshots: hiding the editor resizes the docked node down to the detail width (_dockedAuxiliaryBarWidth). Any _editorSizeGrownForSidebarHide/_detailWidthGrownForSidebarHide snapshot captured earlier (while the editor was visible and the sessions list was hidden) is now stale — restoring it when the sessions list is later shown re-inflates the node so the detail fills the whole side pane instead of the chat reclaiming the freed editor width. setEditorHidden(true) must drop both snapshots in the detail-still-visible branch.

• Overriding a workbench toolbar hover needs matching specificity: the core rule .monaco-workbench .monaco-action-bar:not(.vertical) .action-label:not(.disabled):hover (and the :hover outline rule) sets the toolbar hover background/outline at ~6-7 class specificity. An action-item label that needs to override that hover (either to suppress it for a non-interactive label, or to re-skin it) must use an equal-or-higher-specificity selector (prefix .monaco-workbench ... .monaco-action-bar:not(.vertical) .action-item.<class> .action-label:hover), not a short .<class> .action-label:hover that loses the cascade. (The single-pane diff-stats pill was once suppressed this way while static; it is now a clickable action that opens the multi-file diff, so it keeps the standard --vscode-toolbar-hoverBackground hover.)

• A docked-detail editor must not reveal the editor area while the detail panel is already showing its content — model it as a base editor input the single-pane workbench recognises: the empty Files placeholder (EmptyFileEditorInput) and the Changes multi-diff (SessionChangesEditorInput) surface their content in the docked detail panel (auxiliary bar). Activating one (closing a neighbouring tab so the workbench auto-opens the next editor via editorGroupView.doCloseActiveEditor → doOpenEditor, or clicking the tab) fires onWillOpenEditor unsuppressed and would otherwise reveal the hidden editor area. Both inputs extend the abstract base DockedEditorInput (src/vs/sessions/common/dockedEditorInput.ts, extends EditorInput). The base Workbench.revealEditorOnOpen(e) (the onWillOpenEditor handler — a protected method, renamed from _handleWillOpenEditor) does the generic reveal; SinglePaneWorkbench overrides revealEditorOnOpen and returns early (no reveal) when e.editor instanceof DockedEditorInput && partVisibility.auxiliaryBar && !partVisibility.editor — i.e. only when the detail panel is open and the editor area is closed — otherwise it calls super.revealEditorOnOpen(e). So the docked-editor policy lives in SinglePaneWorkbench (the only workbench with a docked detail panel) via a proper type + the current part visibility, not a per-input marker, a contrib-registered predicate, or a remembered set. Note the condition means that when the detail panel is closed (whole side pane closed), opening a docked editor does reveal the editor area so its content is visible. Caveat: a deliberate open of the already-open Changes tab (session-header pill ViewAllChangesAction) or a file diff (_openMultiFileDiffEditor) while the detail panel is open is still suppressed by this rule, so those must explicitly reveal via revealEditorPartExplicitly() before opening (revealing before the open also avoids the multi-diff hanging while laid out in a hidden 0-size editor part). Keep revealEditorOnOpen a named protected method so it is unit-testable via Reflect.get(...prototype, ...).

• Gate single-pane editor-title layout/view actions on MainEditorAreaVisibleContext; the Create Pull Request bar lives in the title bar, not the editor: single-pane (config.<DOCK_DETAIL_PANEL_SETTING>-gated) editor-title layout/view items (Maximize/Restore, Toggle Details, Hide Editor, Open in Modal, the diff-view actions collapse/expand/toggle-inline/list-tree) must include MainEditorAreaVisibleContext so they disappear when the editor content is closed. The Create Pull Request anchor (CHANGES_HEADER_ACTIONS_ID) is not an editor-title action: it is contributed to Menus.TitleBarSessionMenu (the sessions title bar's session-actions area) by ChangesHeaderActionsAction in changesViewActions.ts, gated on IsSessionsWindowContext + IsAuxiliaryWindowContext.toNegated() + config.<DOCK_DETAIL_PANEL_SETTING> + SessionHasChangesContext (independent of editor-area visibility), and its ChangesActionsBar view item is registered for (Menus.TitleBarSessionMenu, CHANGES_HEADER_ACTIONS_ID) via IActionViewItemService. The docked reveal-sync (_syncDockedEditorVisibility) must be symmetric: it reveals when the node widens past the detail width and hides (sets partVisibility.editor=false, flips MainEditorAreaVisibleContext) when a sash drag squeezes the editor content back down to the detail width — same guards (_syncingDockedEditorVisibility, _suppressDockedEditorRevealSync, _dockDetailPanel, and only while the detail is visible).

• The managed Files placeholder tab is conditional, not always-on: SinglePaneManagedTabsStrategy opens the empty Files placeholder (with the Changes tab) only when the editor group is empty on a view-open trigger (see the "add only when the group is empty" pitfall below), and removes it while a real (non-managed) file/diff is open in a visible editor area. It is not re-added when that file closes — the defaults return only when the group empties and the side pane is reopened. Drive the removal as a one-shot reaction on onWillOpenEditor (a genuinely new real-file open — skip re-activations where group.contains(editor) is already true, non-main-part groups, and restore-driven opens), not a standing autorun/editor-change invariant (that would re-remove a Files tab the user just added via +). Close/open the placeholder under suppressEditorPartAutoVisibility().

• A per-session aux-bar (detail) capture must be skipped during a session-switch restore: the D2 onDidChangePartVisibility listener that records a created session's detail visibility must bail while _isRestoringSessionLayout is true. During restore an external component (e.g. DetailPanelController) can transiently reveal the aux bar for the incoming active editor; capturing that overwrites the session's saved detail-hidden state, so switching back shows the detail even though the user had closed it. Keep the aux-bar sync work synchronous (fire-and-forget the view-open calls) so the restore epoch ends promptly and legitimate post-restore user toggles are still captured.

• The detail-panel forced reveal must be gated on the editor content being visible: DetailPanelController._syncForcedTarget reveals the docked detail (aux bar) when a Changes/File editor becomes active while the detail is hidden. That reveal must additionally require isVisible(EDITOR_PART, mainWindow) — otherwise, on a window reload where the user had closed the whole side pane (editor + detail both hidden, persisted), the restored managed tab becoming active re-reveals the detail and the closed state is lost. Reveal the detail only to accompany a visible editor; when the whole pane is intentionally closed, leave it closed.

• Auto-managed tabs stay user-closable via "add only when the group is empty" — not a dismissal set: SinglePaneManagedTabsStrategy owns the managed Changes/Files docked tabs. They re-ensure on many signals (session state, editor visibility, editor changes), so naively re-creating them makes a close feel un-closable (they are non-preview pinEditor, NOT sticky — they do have close buttons; the blocker is the re-ensure). The clean rule that needs no _dismissedManagedTabs bookkeeping: open the default tabs only when the editor group is completely empty (group.editors.length === 0), and only on a "view opened" trigger — a session switch (the add-allowed session-state autorun) or the layout service's onDidRevealSidePane event (fired by the workbench whenever the docked editor part and/or aux-bar detail transitions from fully hidden to visible). A plain editor-list / visibility change reconciles (e.g. removes the Files placeholder while a real file is open) but is add-disallowed. Why this is close-respecting for free: closing one managed tab while another (or a real file) remains leaves the group non-empty → not re-added; closing the last one closes the side pane → reopening it (empty group) restores the defaults. Opening a file fires onDidRevealSidePane too, but the sync is deferred on the docked-tab sequencer (which runs after onWillOpenEditor has added the editor), so the group is non-empty when it runs → defaults are not forced back → closing that file still closes the side pane. The add-disallowed editor-change trigger is essential: without it, closing the last tab (group empty) would immediately re-add the defaults and the pane could never close. The layout-driven add is done on the settled restore, not during it: the base controller fires onDidEndSessionLayoutRestore when the restore depth returns to 0 (after the — possibly async — working-set apply completes), exposed via ISinglePaneLayoutContext; the strategy reconciles off that ([Trigger D], openDefaultsIfEmpty: true). This is required for a new session, whose empty working set closes the previous session's docked tabs after the switch — reading the group during the async apply (an editor-change trigger) races the empty state and drops the Files tab; reconciling on the settled restore-end reads the reliably-empty group. Do not gate the add on isRestoringSessionLayout captured in the editor-change autorun — that fires mid-apply and is fragile. A user file-open/close is not a restore, so it stays add-disallowed and a close still sticks. One exception — new-session submit: when the active session transitions isCreated false → true (in place, or via a resource-replace commit), the new-session view already holds the Files placeholder, so the empty-group rule would skip opening Changes; the submit transition is treated as a one-shot "ensure the Changes tab (pinned first, opened active)" even when the group is non-empty — opening it active (not inactive) is what makes the detail panel map to the Changes container rather than the still-present Files placeholder; it is a genuine one-time transition, so it never fights a later user close. Because submit fires two triggers (the session-state autorun's ensureChangesActive and, via the submit restore, onDidEndSessionLayoutRestore's Trigger D), a single shared generation counter would let the later trigger's reconcile supersede and drop the earlier's intent — so the triggers' intents are accumulated (mergeTriggers, OR-combined into a pending trigger consumed by the surviving reconcile, re-merged in finally if superseded mid-run) rather than replaced. Scope the pending intents to the session they were queued for (IPendingReconcile.sessionKey = the active session resource): a reconcile can be superseded mid-await (e.g. it stalls opening the Changes editor) by a session switch; if the superseded reconcile's finally merged its old trigger back unconditionally, an ensureChangesActive/ensureAllInputs intent for session A would leak onto session B and reopen a user-closed tab or activate Changes for the wrong session. Merge back (and accumulate on queue) only when the successor targets the same sessionKey; a session switch drops the previous session's stale intents. Second exception — a details-only reveal: when onDidRevealSidePane fires with the aux-bar detail panel visible but the editor area hidden (isVisible(AUXILIARYBAR_PART) && !isVisible(EDITOR_PART)), the docked details panel shows the managed docked inputs, so they are ensured (Changes if created + Files) even when the group is non-empty — restoring one the user had closed earlier. This is tied to the reveal gesture (a close within an open details view still sticks until the next reveal); an editor-included reveal keeps the strict empty-group rule. Do NOT re-introduce a _dismissedManagedTabs set, an onDidCloseEditor dismissal listener, infer the reopen from aux-bar visibility, or gate on a generic "side pane became visible (editor || aux)" check. The empty Files placeholder is tidied away when a real workspace file opens — a one-shot reaction on onWillOpenEditor (a real file/vscode-remote input, skipped during a restore), not a standing "no placeholder while a real file is open" invariant enforced every reconcile. The standing invariant broke + Files: adding the placeholder while a file was open re-triggered the reconcile which immediately removed it again. Because + Files opens an EmptyFileEditorInput (not a real file), the one-shot listener ignores it, so a user-added Files tab survives while a real file is open (a tidy [Changes][file] strip still results from a real-file open).

• Aux-only managed inputs are a state invariant, not a reveal-time exception: whenever the Auxiliary Bar is visible and Editor is hidden, every managed-tab reconcile must re-read that current composition and ensure both Changes and the empty Files input, even in a non-empty group. Do not capture Aux-only state on onDidRevealSidePane; queued work can run after the composition changes, and closing either managed input while Aux-only must restore it immediately.

• Observe single-pane part visibility as a signal when the composition matters: deriving editorVisible || auxiliaryBarVisible suppresses Editor+Aux → Aux-only transitions because the derived boolean stays true. Managed-tab reconciliation must react to every relevant part-visibility event, then read the settled Editor/Aux composition when queued work executes.

• Editor-area collapse (closing non-docked tabs) fires only on a detail-only hide, never when the whole side pane closes: SinglePaneEditorAreaCollapseStrategy reacts to the editor part hiding by closing every non-docked editor (capturing reopenable ones, dropping non-restorable ones). It must gate that on the aux bar still being visible (isVisible(AUXILIARYBAR_PART)): a Detail-only hide (Hide Editor keeps the detail) collapses the editors, but closing the whole side pane (both editor + aux hidden) must leave the editors intact so they return when the pane is reopened. The gate is reliable because the two hide paths order their setPartHidden calls consistently — toggleSidePane hides the aux bar before the editor, so when the editor-hidden event fires the aux is already hidden (⇒ skip collapse); Hide Editor sets the aux visible before hiding the editor (⇒ aux visible ⇒ collapse). Don't collapse purely off "editor part hidden" — that also dropped dirty/non-restorable editors when the user just closed the side pane.

• D10 (empty aux-bar cleanup) must gate on quick-chat, not the racy container-active check, or it flickers the side pane closed on reload: the Agents-window Changes/Files aux-bar views gate on SessionHasWorkspaceContext + WorkspaceFolderCountContext, which are set asynchronously (via the setActiveSessionContextKeys autorun reading the session's async workspace) after a session activates/reloads. So right after D3b/DetailPanelController/a manual toggle reveals the aux bar, isViewContainerActive(Files/Changes) is transiently false (context keys not settled) even for a real workspace session. The D10 reconcile (_syncAuxiliaryBarPartVisibility, which runs synchronously on the onDidChangePartVisibility(visible) signal and only ever hides) then closes the just-opened side pane, and since it never re-reveals, it stays closed — the reload "side pane opens then closes" flicker, "Files not shown when opening the side pane", and "new-session side-pane state not remembered". Fix: D10 hides only when the aux is genuinely empty for the active session's lifetime — no active session, or a workspace-less quick chat (activeSession.isQuickChat?.get() === true, its Changes+Files permanently gated off) — never for a workspace-backed session whose gating context keys are merely still settling. Do NOT use the transient _hasActiveAuxViewContainers() result to hide a workspace session's aux.

• DetailPanelController must not hide the detail on an empty editor group in the new-session view: _computeTarget returns Hidden when the main editor part is empty (a created session's all-tabs-closed → whole side pane closed). But the new-session (uncreated) view's editor group is transiently empty while its Files tab is (re)ensured, and its Files detail is open by default and owned by the layout controller's D3b. Gating the empty-group Hidden on activeSession.isCreated avoids a transient hide that the D2 visibility listener would otherwise capture as the new-session preference — making every subsequent cmd+n open with the side pane hidden. Combined with the editor-visibility reveal gate, the new-session default stays open while a user's explicit hide is still remembered (D3b _newSessionViewState).

• Don't mirror an environment fact onto a shared widget API: an Agents-window check (e.g. "is this the sessions window?") belongs on IWorkbenchEnvironmentService.isSessionsWindow, read directly by the consumer that needs it (e.g. getChatAccessibilityHelpProvider in chatAccessibilityHelp.ts injecting the service itself). Do not add an isSessionsWindow-style property to a shared interface like IChatWidget just to thread that fact through — it leaks a sessions-specific concept into shared workbench chat surfaces and every future consumer would need the same plumbing instead of injecting the service once.

• A view-lifecycle setChat/setModel-style hook can be re-invoked for the same underlying resource: ChatView.setChat fires again on unrelated status/interactivity observable changes, not only on a genuine view swap. A consumer like ResponseSelectionSideChatController that force-dismisses its own transient UI on every call discards an in-progress draft and, worse, clears a pending busy submission mid-flight, letting a duplicate submission race in. Compare the incoming resource against the previously tracked one and only treat a genuine change (or the first call) as dismiss-worthy; a same-resource re-invocation must preserve visible/busy state.

• A pending async submission's completion/error handler must no-op after a genuine force-dismiss, not just after a same-resource re-invocation: even with the same-resource guard above, ResponseSelectionSideChatController._submit's createAndSendSideChat().then()/.catch() can still settle after the user has genuinely navigated away (a different-resource setChat, or any other force-dismiss) — reopening the overlay, restoring the typed query, refocusing the input, or showing a stale error notification for UI the user already dismissed. Capture a _generation counter bumped only on a genuine force-dismiss, snapshot it before the async call, and have the settle handlers bail when the counter no longer matches; don't rely solely on resource comparison, since the overlay's own dismissed state (not the chat identity) is what must gate the mutation.

Validating Changes

You must run these checks before declaring work complete:

1. npm run typecheck-client — TypeScript compilation check. Do not run tsc directly.
2. npm run valid-layers-check — MANDATORY. Catches layering violations. If this fails, fix the imports before proceeding.
3. scripts/test.sh --grep <pattern> — unit tests for affected areas

Progress dashboards / local HTML in the integrated browser

• The integrated browser blocks file:// outside trusted workspace folders (403 "File does not reside within a trusted folder"). To preview session-folder HTML (e.g. a live progress dashboard), serve it over http://127.0.0.1:<port> with a background python3 -m http.server and open that URL instead.
• For a self-updating dashboard, embed <meta http-equiv="refresh" content="5"> and keep the HTML task data in lockstep with the todo store — update both at every task transition so they never drift.

Don't rely on the LLM to render links/actions from tool result text

• Tool result text is fed to the model, which may drop or reformat markdown links (e.g. render a session URI as an inline code span), so an explicit [label](uri) in a tool result is NOT a reliable way to give the user a clickable action.

• For a deterministic, client-rendered action (a "pill"/button) tied to a specific tool call, set toolSpecificData on the ChatToolInvocation in stateToProgressAdapter.ts (keyed on the tool name + parsed result) and add a custom subpart in chatToolInvocationPart.ts — the completed-state section already routes custom toolSpecificData kinds (see resources/simpleToolInvocation). Follow the agentFeedbackReviewConfirmation pattern.

• Managed-tab reconciliation must run entirely under suppressEditorPartAutoVisibility(): SinglePaneManagedTabsStrategy._reconcileCore closes stale/foreign managed tabs (e.g. a restored Changes tab whose session's workspace hasn't resolved yet on reload) via _closeForeignChangesEditors before ensuring the current ones. If any close runs unsuppressed and empties the group, the workbench handleDidCloseEditor docked branch treats it as "user closed all tabs" and closes the whole side pane — the reload flicker where the side pane appears then vanishes. Wrap the full reconciliation body in one suppression window so transient empty states are never mistaken for a user action; don't rely on per-open suppressions alone. (Historical note: the managed Files placeholder was once removed/re-added reactively with a _dismissedManagedTabs set; that bookkeeping is gone — see the "add only when the group is empty" pitfall.)

• Layout-driven editor closes (working-set apply) must not be mistaken for user closes: On any single-pane session switch (incl. Cmd+N to a new untitled session and reload), the base controller applies the target session's editor working set — an empty working set closes the managed Changes/Files tabs externally. The workbench handleDidCloseEditor docked branch would otherwise see the empty group and close the whole side pane (reload/Cmd+N flicker: pane/Files-tab appears then vanishes). Fix: _withSessionLayoutRestore (base controller) holds suppressEditorPartAutoVisibility() for the whole (async) restore only when isSinglePaneLayoutEnabled (OFF layout unchanged), so layout-driven closes never reach handleDidCloseEditor. suppressEditorPartAutoVisibility() on IAgentWorkbenchLayoutService returns the IDisposable suppression window; the boolean it toggles is observed internally through the Workbench's protected _isEditorPartAutoVisibilitySuppressed getter. (Historical note: this fix also once protected a _dismissedManagedTabs set from being poisoned by external closes; that set no longer exists — managed tabs are now re-populated purely by "add only when the group is empty on a view-open trigger".)

• DetailPanelController must not force-reveal the detail during a layout-driven restore: _syncForcedTarget reveals the aux-bar detail to accompany the active Changes/Files editor. On a session switch the target session's editor working set is restored, making its Changes/Files editor active — an editor change that is NOT a user open. If the user had hidden the detail for that session, that restore-driven editor change would force-reveal it, losing the per-session detail-hidden state. Gate the reveal (setPartHidden(false, AUXILIARYBAR)) on !isEditorPartAutoVisibilitySuppressed() (in addition to the existing editor-visible guard): during _withSessionLayoutRestore the base controller holds suppressEditorPartAutoVisibility() (single-pane), so a restore-driven forced target skips the reveal while a genuine user editor open (unsuppressed) still reveals. Note the existing [D3c/single-pane] test passed because it simulated the reveal synchronously during apply (so D3 re-hid last); the real bug is the async DetailPanelController reveal firing on the editor-change after D3 already hid.

• The width-based docked reveal-sync (_syncEditorVisibility) must bail while editor-part auto-visibility is suppressed: SinglePaneWorkbench._syncEditorVisibility reveals/hides the docked editor purely from the node width (for user sash drags). A session-switch / reload layout restore holds suppressEditorPartAutoVisibility while it applies the working set, which can widen the docked node before the controller has set the target editor-part visibility. Because the width-sync ran regardless of suppression, restoring a Detail-only session (aux open, editor closed) flickered the editor open on switch (the working-set apply widened the node → reveal → the controller then re-hid it) and could persist it open on reload. Gate _syncEditorVisibility on !this._isEditorPartAutoVisibilitySuppressed (alongside the existing _syncingEditorVisibility reentrancy guard) so only a real user sash drag (unsuppressed) drives width-based visibility. Relatedly, baseSessionLayoutController._applyWorkingSet's isInitialRestore branch must, for single-pane, apply _shouldHideEditorPartOnApply(editorPartHidden) after the working-set apply (a no-op for the classic layout) — otherwise a Detail-only session's persisted editor-hidden state is not re-applied on reload and the editor is left visible.

• Single-pane detail ownership is split cleanly between shared visibility and contextual content: SinglePaneSidePaneVisibilityStrategy persists exactly two durable { editorVisible, auxiliaryBarVisible } profiles (New and Existing), suppresses Quick Chat without storing it, and restores those profiles across navigation/reload. SinglePaneDetailPanelStrategy maps the active editor to Changes/Files and may transiently hide Aux for Browser/no-content states, but those effective hides must never overwrite the durable profiles. Do not reintroduce per-session aux state, saved-container machinery, or a third cleanup strategy.

• Single-pane is a sibling of the desktop controller and composes strategy objects — it does not extend LayoutController: SinglePaneLayoutController extends BaseLayoutController directly. Its current strategies are SinglePaneSidePaneVisibilityStrategy, SinglePaneDetailPanelStrategy, SinglePaneDetailsStrategy, SinglePaneManagedTabsStrategy, and SinglePaneEditorAreaCollapseStrategy; the docked-tab strategies share SinglePaneDockedTabsCoordinator. Shared controller state is exposed through ISinglePaneLayoutContext. View-state strategies register immediately, while managed-tab/collapse strategies register after LifecyclePhase.Restored.

• Single-pane detail/tab behaviour lives ON the layout controller (or its strategies), not in separate contribution controllers or a shared service: SinglePaneLayoutController owns both the managed docked tabs (pinned Changes multi-diff + empty Files placeholder) and the detail-panel mapping (active editor → Changes/Files container, aux-bar reveal/hide). They were previously ChangesTabController/DetailPanelController (registered by a SinglePaneModeController contribution) coordinating via global IAgentWorkbenchLayoutService flags, then briefly via an ISessionLayoutCoordinatorService. Both were removed: "is a session-switch restore in progress?" is just the base protected getter this._isRestoringSessionLayout (set by _withSessionLayoutRestore) — surfaced to the strategies via ISinglePaneLayoutContext.isRestoringSessionLayout — so a restore-driven editor change never force-reveals the detail or dismisses a managed tab. The base controller has IChangesViewService + IContextKeyService deps and a protected _editorGroupsService (a subclass can't add DI ctor params without redeclaring all base params, so shared services live on the base). Tests: the layout harness got activeGroupEditors/closeSuppressionFlags, a real mainPart.activeGroup, an activateAux opt-in that resolves the lifecycle, and a TestSinglePaneController.runWithRestore(...) seam to hold _isRestoringSessionLayout across an async editor change; changesTabController.test.ts was deleted and its scenarios moved into desktopSessionLayoutController.test.ts.

• Single-pane created-session default is Editor-only (Changes editor, detail closed) — the detail is not force-opened by editor activation: a Changes/file editor becoming active must NOT auto-reveal the docked detail (aux bar). SinglePaneDetailPanelStrategy._syncForcedDetailTarget reveals a hidden detail ONLY when it was temporarily hidden by a full-width editor (_hiddenByFullWidthEditor), never when it is hidden by the per-session default or an explicit user hide; when the detail is visible it still switches the container (Changes/Files) to match the active editor. Exception — opening the empty Files placeholder (EmptyFileEditorInput) reveals the Files detail (its content, the Files tree, lives in the aux bar). This is a dedicated onDidActiveEditorChange listener in the strategy that reveals the aux bar when the placeholder becomes the active editor — NOT reactive logic inside the detail autorun (which re-reads auxBarVisibleObs, so it would re-reveal the instant the user hides the detail — bug: "can't hide the details view in the empty file editor at all"). Keying on active editor (not onWillOpenEditor) is deliberate: the managed auto-ensured Files tab is opened inactive as a background tab (fileTabOptions), so it never becomes active and never reveals — preserving the Editor-only default — while the + Files action and selecting the Files tab both make it active and reveal. Do NOT reveal from the NewFileTabAction instead: that misses tab-selection and other activation paths (tried and rejected — "does not work"). The listener is guarded by isVisible(EDITOR_PART) (don't reveal the detail alone while the whole side pane is closed, e.g. Scenario C reload) and !ctx.isRestoringSessionLayout (a restore-driven activation must not reveal). Because hiding the aux bar fires onDidChangePartVisibility, not onDidActiveEditorChange, the user's hide sticks while the placeholder stays active. Do NOT reintroduce a DetailPanelTarget.FilesReveal in the autorun or an isEditorPartAutoVisibilitySuppressed() layout-service API — the active-editor listener needs neither. The reopen default is workbench-layout policy via _defaultSidePaneState (SinglePaneWorkbench = editor-only); the controller only filters it against available content. When changing this, update the [single-pane] reveals the Files detail when the empty Files placeholder becomes active and [Scenario C] tests together.

• Header overflow belongs before trailing layout controls, not promoted into the inline action strip: keep secondary menu items in the toolbar's secondary group so they remain under .... Render trailing layout actions from a separate header menu after that toolbar, with a separator between the two action hosts; do not make secondary actions primary just to change the overflow button's position.

• A toolbar-host separator must follow rendered actions, not menu presence: a configured layout menu can have zero visible items after context-key evaluation. Enable the secondary toolbar's trailing separator from the layout toolbar's actual item count and rebuild it when that menu changes, or the header can retain an orphan separator.

• Hide Editor and Toggle Details share visibility, but not enablement: when an editor supports docked details, keep both actions visible so the trailing layout group stays stable. Gate Hide Editor with AuxiliaryBarVisibleContext as a precondition, so hiding details disables the action instead of removing it.

• Code Review switches between right-inline and first-overflow placement: while MainEditorAreaVisibleContext is true, contribute Run Code Review to the right header menu in the first primary group (0_codeReview). While false, contribute it to secondary/1_codeReview, so it is first in ... with a separator after it; keep both placements mutually exclusive and retain identical applicability gates.

• Bridge extension editor-title actions into the right header with standard semantics: EditorTitleMenuBridgeContribution mirrors extension-owned MenuId.EditorTitle commands and submenus into Menus.SessionsEditorHeaderSecondary. Map navigation to an inline extension group and every other group to secondary/extension/<original-group> so non-navigation actions stay in overflow; forward the active editor's original URI as the menu argument.

• R1 (new-session editor hide) must be transition-triggered, not level-triggered on the active editor: hiding the editor in the new-session view must fire only when the editor just became visible (visibility false→true) or when the view was just entered with the editor already visible (inherited-visible editor) — never merely because the active editor changed to a managed placeholder while the editor is already visible. A level-triggered rule ("hide whenever active editor is non-real content and editor visible") wrongly hides the editor when the user switches to the Files tab with a file already open (the reveal-sync suppression re-arm clears isEditorRevealedExplicitly, so the level rule then hides). Track previousEditorVisible + previousInNewSessionView in the autorun and hide only on (editorJustRevealed || justEnteredNewSessionView) && !isEditorRevealedExplicitly(). The two workbench methods setSuppressDockedEditorRevealSync (blocks width-based reveals at the source, avoiding flicker) and isEditorRevealedExplicitly (distinguishes an explicit toggle-details-off/file-open reveal that must stick) are still required by R1 — they are independent of the ChangesTab/DetailPanel controller merge.

• Single-pane created sessions need the docked editor part revealed on switch — the isModal gate in _applyWorkingSet skips it: baseSessionLayoutController._applyWorkingSet only reveals the editor part when !isModal (i.e. workbench.editor.useModal !== 'all'), because in the classic layout editors open in a modal part. But in single-pane the docked editor lives in the grid even when useModal is 'all' (the default), so that gate wrongly skips the reveal and a created session's side pane looks fully closed (worse once the Changes editor no longer force-reveals the detail). Fix: compute revealEditorPart = !editorPartHidden && !isInitialRestore && (isSinglePaneLayoutEnabled ? isCreatedSession : !isModal) and also reveal for the 'empty' working-set case in single-pane (a first-visit created session has no saved editors but still shows its managed Changes editor). This restores the Editor-only default while respecting the per-session editorPartHidden (Detail-only / side-pane-closed) state and excluding new-session views (R1 keeps their editor closed). Note the layout test harness leaves isSinglePaneLayoutEnabled falsy by default, so base single-pane branches are inert in tests unless a test opts in via the singlePaneLayoutEnabled create option.

• A draft replaced by a committed session must inherit the draft's side-pane layout before _applyWorkingSet runs: some providers commit a new-session draft by firing onDidReplaceSession with a new session resource, not by flipping isCreated on the same resource. Without transferring the active draft's _editorPartHiddenBySession and aux-bar state, the committed resource has no saved layout, so the delayed B2 working-set apply treats it as a first-visit created session and reveals the editor (Editor-only default) even though the user submitted from the new-session Detail-only view. Handle the replacement event as D4 submit: copy the active draft's editor-hidden state to the committed resource, record Changes as the committed aux container, and open Changes only if the draft detail was visible; switching to an unrelated existing created session still uses the Editor-only default.

• Single-pane D3c: a created session with NO saved detail state must be left in its current on-screen state — never force-hidden: the detail (aux-bar) restore for a created single-pane session (SinglePaneDetailVisibilityStrategy._syncDetailVisibility D3c) must only act when viewStateBySession has a saved entry — hide when it says hidden, reveal when it says visible. When there is no saved state (savedState === undefined), return without touching the aux bar. Force-hiding on the no-state path re-closes the detail the user had open in the new-session view on submit: the committed session's resource can change again after the initial draft→committed transition, so a later restore run lands in D3c with no saved state and previousIsCreated already true (the intrinsic !previousIsCreated && isCreated submit detection ([D4]) no longer matches), and would re-hide. Leaving the current state also covers a first-time-seen created session gracefully; the detail-panel strategy keeps the container in sync, and the visibility is captured on the next switch-away or user toggle. (The intrinsic [D4] submit routing to _onNewSessionSubmitted is still kept for the clean first transition — it records the state and opens Changes — but D3c-leave-current is the backstop for every follow-up run.)

• A replace-based submit must be detected intrinsically in the aux/detail restore autorun (!previousIsCreated && isCreated), not via _onSessionReplaced: the same ordering trap as the editor reveal, but for the detail (aux-bar) visibility. sessionsService listens to onDidReplaceSession first (it's a core service) and its handler calls updateSession → sets activeSession in a transaction → the single-pane SinglePaneDetailVisibilityStrategy D3 restore autorun fires synchronously inside that handler. The layout controller's _onSessionReplaced (registered later, at BlockRestore) runs after — so any aux-state transfer it does is too late: the autorun has already run D3c. The classic same-resource isSubmit guard (!isSessionSwitch && !previousIsCreated && isCreated) misses this because the agent-host/Copilot provider commits by replacing the draft with a new resource (isSessionSwitch is true). Fix: relax isSubmit to previousSessionResource && !previousIsCreated && isCreated && !viewStateBySession.has(activeSessionResource) — detect the submit purely from the transition, independent of _onSessionReplaced ordering. The !has(state) guard keeps a genuine navigation from a draft to an existing created session on the normal D3 restore path. _onSessionReplaced then only needs to cover the background submit (a session committed while a different session is active, so the autorun never fires for it). Because the committed resource can still change again after the first transition, this intrinsic detection alone isn't enough — pair it with the D3c-leave-current rule above. General rule: for any "on submit, preserve/transfer layout" logic, detect the submit from the reactive transition the consumer already observes — never from a flag/transfer set by a separately-registered onDidReplaceSession listener.

• onDidReplaceSession always means submit — never re-check from.status === Untitled, and never try to preserve visibility via a flag consumed by runOnChange: two related traps when suppressing the docked-editor reveal on new-session submit. (1) By the time onDidReplaceSession fires, the draft has already transitioned Untitled→Completed, so a _isNewSessionReplacement(from,to) guard checking from.status === SessionStatus.Untitled is always false and silently skips the whole editor-hidden/aux transfer. The event is documented to fire only when an untitled draft is atomically replaced by its committed session, so treat every onDidReplaceSession as a submit — no status guard. (2) The B2 working-set runOnChange (on the workspace-gated activeSessionForWorkingSet derive) fires before the synchronous onDidReplaceSession handler, so a boolean flag set in _onSessionReplaced and read synchronously in runOnChange is captured stale (false) and cannot suppress the reveal. The correct, ordering-robust mechanism is to have _onSessionReplaced write the draft's live editor-part visibility into _editorPartHiddenBySession[to] synchronously; because _applyWorkingSet reads that map inside its Sequencer.queue async microtask body (which runs after the sync replace handler), the reveal decision (_shouldRevealEditorPartOnApply/_shouldRevealEditorPartForEmptyWorkingSet) sees editorPartHidden=true and skips. Do NOT add a preserveEditorPartVisibility apply option keyed off event ordering — it's impossible to set in time.

• R1 can drop setSuppressDockedEditorRevealSync — always hide on new-session-view entry instead: the width-based reveal-sync suppression (setSuppressDockedEditorRevealSync/_suppressDockedEditorRevealSync) was removed. It did two jobs: (1) block a momentary width-reveal of the editor in the new-session view, and (2) clear _editorRevealedExplicitly on entering the view so R1 re-hides an inherited-explicit editor across a session switch (the working-set apply runs under suppressEditorPartAutoVisibility, so handleDidCloseEditor doesn't clear the flag naturally). Job (1) is now handled by R1 re-hiding any non-explicit reveal (a sash-drag reveal flickers then re-hides — acceptable). Job (2) is handled by making R1's hide condition justEnteredNewSessionView || (editorJustRevealed && !isEditorRevealedExplicitly()) — i.e. entering the new-session view always resets to editor-closed (a stale cross-session explicit flag can't keep the editor open), while the explicit flag is only honored for in-session reveals (toggle-details-off revealing the empty editor). isEditorRevealedExplicitly is still needed for that in-session case.

• Quick chats have no side pane — don't auto-reveal the editor part, and hide it when switching in from a session that had it open: in single-pane, SinglePaneLayoutController._shouldRevealEditorPartOnApply must exclude quick chats (!editorPartHidden && isCreatedSession && !isQuickChat); a created quick chat would otherwise reveal the docked editor part on switch (bug: "side pane opened automatically for quick chat"). Excluding the reveal is not enough — switching in from a workspace session leaves the editor part visible (the working-set apply is suppressed and never hides it), so a dedicated _registerQuickChatEditorHide() autorun hides the editor part while a quick chat's editor group is empty (gated on _isMainPartEmpty() so a real editor, e.g. the integrated browser, opened in a quick chat is never hidden). The aux bar is already handled by D10 + the detail-panel Hidden target.

• Single-pane per-session editor-part visibility must be restored both ways — _applyWorkingSet only ever revealed it: baseSessionLayoutController._applyWorkingSet revealed the editor part when a session wanted it visible but never hid it, so returning to a session whose docked editor was closed (Detail-only or whole side pane closed) left the editor visible/inherited from the previously-active session (bug: "side pane opened when returning to a session where it was closed"). The per-session _editorPartHiddenBySession state was only consumed to suppress the reveal (!editorPartHidden), never to actively hide. Fix: add a symmetric Template-Method hook _shouldHideEditorPartOnApply(editorPartHidden) (base returns false — classic layout doesn't treat editor-part visibility as per-session; single-pane returns editorPartHidden && isCreated && !isQuickChat) and, in both the empty and non-empty _applyWorkingSet branches, hide the editor part (mutually exclusive with revealing, skipped on isInitialRestore which preserves the workbench-restored visibility). The hide runs inside _withSessionLayoutRestore's suppressEditorPartAutoVisibility window so it is never mistaken for a user close. Note the aux bar was already restored both ways by the inherited D3 _syncAuxiliaryBarVisibility; only the editor part lacked the hide.

• Explicit managed-editor opens must reveal outside the auto-reveal path — and mark the reveal explicit: docked-detail Changes/Files editors (DockedEditorInput) are kept from revealing the docked editor by SinglePaneWorkbench.revealEditorOnOpen (see the entry above), so tab activation and layout-driven restores do not reveal it. A deliberate user gesture that should show managed editor content (session-header Changes pill ViewAllChangesAction, opening a file diff in _openMultiFileDiffEditor) must reveal the editor part before opening the managed editor via IAgentWorkbenchLayoutService.revealEditorPartExplicitly() — not the generic setPartHidden(false, EDITOR_PART). The generic call routes to setEditorHidden(hidden, explicit=false), leaving _editorRevealedExplicitly = false, so R1 / the working-set apply (_shouldHideEditorPartOnApply) can re-hide it (especially across a session-switch race). revealEditorPartExplicitly() sets the explicit flag (and re-asserts it even when already visible, since setEditorHidden early-returns when the part is already visible). Do not weaken the DockedEditorInput reveal suppression or add timing delays.

• Per-session editor-part (side-pane) hidden state must be captured eagerly on the visibility change, not lazily re-read at switch-away: baseSessionLayoutController._saveWorkingSet used to record _editorPartHiddenBySession[prev] = !isVisible(EDITOR_PART) at the moment it saved the outgoing session. That races: the working-set derive (activeSessionForWorkingSet) lags the raw activeSession (it gates on workspace-folder readiness), so other autoruns driven by the raw active session (managed-tab open, D3 aux sync) have already revealed the editor for the incoming session by the time _saveWorkingSet(prev) runs — so the previous session gets recorded as editorPartHidden=false and its closed side pane reopens on return (symptom: only the editor content re-appears, details stay closed, and no setEditorHidden fires on the switch because nothing on the switch path toggles it). Fix: capture it in a [B2] onDidChangePartVisibility(EDITOR_PART) listener (mirroring the existing [B1] panel-visibility capture) guarded by !multipleSessionsVisibleObs && !_isRestoringSessionLayout, so the value is written the instant the user closes/opens the side pane and layout-driven restore changes are ignored. Remove the lazy read from _saveWorkingSet entirely (keeping it would let the racy switch-time value overwrite the good eager one). The unit harness can't reproduce the derive-lag, so add a focused test that fires the EDITOR_PART event to assert eager capture, plus one that fires a reveal inside _withSessionLayoutRestore to assert the captured closed state is preserved.

• Single-pane detail sync must re-read aux-bar visibility when queued work runs: the detail-panel autorun queues container opens through a sequencer, so a task can be computed while the previous session's detail is visible and run after D3 has restored the incoming session's detail to hidden. Do not trust an auxBarVisible value captured before the queue boundary; read isVisible(AUXILIARYBAR_PART) inside the queued sync, otherwise openViewContainer can re-reveal the detail and overwrite the incoming session's saved hidden state.

• The managed Changes tab must open non-stealing so the working-set-restored active editor is preserved: on a single-pane session switch, baseSessionLayoutController._applyWorkingSet restores the session's editor working set including which editor was active (e.g. package.json). SinglePaneManagedTabsStrategy then idempotently re-ensures the pinned Changes tab — but if changesEditorOptions opens it as active (no inactive / activation), it steals active state from the just-restored editor, so the wrong tab is active after the switch. Give changesEditorOptions inactive: true + activation: EditorActivation.PRESERVE (matching fileTabOptions); the workbench still makes it active when the group is empty (active: this.count === 0 || !options?.inactive, editorGroupView.doOpenEditor), so the first-visit created-session default (Changes active) is preserved while a restored session keeps its own active editor.

• Save the outgoing session's working set eagerly on the raw active session change, not on the workspace-gated activeSessionForWorkingSet derive: the derive (baseSessionLayoutController) holds back while the incoming session's workspace folders resolve, and other autoruns driven by the raw ISessionsService.activeSession (e.g. the single-pane managed-tabs sync) async-close the outgoing session's docked editors (_closeInactiveChangesEditors) during that lag. If the working-set save is on the lagged derive it runs after those closes, so the outgoing session's Changes tab (or whichever editor was active) is already gone and its active state is lost — on return the working set restores the wrong active editor (symptom: switching back to a session whose Changes tab was active shows a different tab active). Fix: a dedicated [B2] runOnChange(activeSession, …) saves the previous session's working set synchronously (guarded by resource-inequality, !Untitled, !_isRestoringSessionLayout) — this runs before the managed-tab sequencer microtask closes anything — and the save is removed from the gated apply runOnChange (which now only applies). Save doesn't need workspace readiness; only apply does. Pairs with making the managed Changes tab open non-stealing (inactive: true + EditorActivation.PRESERVE) so the restored active editor is preserved. The unit harness can't reproduce the derive-lag directly, so assert the decoupling: switching to a session whose workspace isn't in the folders (gated apply holds back) still records a saveWorkingSet for the outgoing session.

• Docked side-pane width persistence must be symmetric about the detail (aux) width: in single-pane the docked detail (auxiliary bar) lives inside the editor grid node, so the workbench persists the pure editor-content width (_persistedEditorWidth = node − detail) and the grid descriptor reconstructs node = editor-content + detail. These must use the same condition for including the detail: only when the detail is visible (partVisibility.auxiliaryBar). Subtracting the detail width unconditionally at save while adding it back only when the detail is visible shrank an Editor-only session's side pane by the detail width on every reload, compounding toward zero ("side pane always tiny on reload"). Fix _persistedEditorWidth to subtract only when the detail is visible.

• Side-pane (editor grid node) size is workbench-level, not per session: the editor grid node width is owned by the workbench grid and persisted globally (workbench.sessions.partSizes via _savePartSizes/createDesktopGridDescriptor), so switching sessions keeps the same width and reload restores it in one paint. Do not add a per-session width map in the layout controller that re-applies a width on session switch/reveal — it makes switching sessions jump the side pane around, and a post-paint restore on reload flickers.

• Express equal sibling sizing through the grid, not width arithmetic in a part: reveal the side pane with SerializableGrid.setViewVisible(editorPartView, true, Sizing.Distribute). The visibility operation already knows the view location and can distribute its containing split; do not add a separate distribution API that requires passing the same view again. Do not compute percentages from the window/sidebar or expose a fixed preferredWidth; those duplicate grid geometry and make the relationship less descriptive.

• Single-pane must not smart-hide the Sessions sidebar: opening or closing Details and opening a real editor leave the sidebar untouched at every window width. The sidebar is an explicit user-controlled surface in this layout; keep responsive auto-collapse confined to the classic desktop controller.

• Single-pane side-pane visibility is shared by lifecycle type, not individual session: persist independent { editorVisible, auxiliaryBarVisible } profiles for New Sessions and Existing Sessions. Ordinary type navigation captures outgoing and applies incoming; submit instead preserves the on-screen composition and seeds Existing from it to avoid a jump. Let quick chats suppress the pane without overwriting either profile.

• Submit activates Changes only when changes exist: record a per-session pending Changes activation on the New→Existing transition, keep Files active while the submitted session has no file changes, then activate Changes when session.changes becomes non-empty. The activation must remain scoped to that session and must not reveal Editor.

• Aux-only width belongs to layout, not lifecycle visibility profiles: DockedAuxiliaryBarController.DEFAULT_WIDTH (300px) is only the no-history initial value. Once the user drags the detail sash, _dockedAuxiliaryBarWidth is directly authoritative for Editor-hide, Aux-show, session switches, and reload, including values below 300px. Do not wrap a direct property return in a helper, floor transitions back to the default, or persist width in New/Existing visibility profiles.

• Core editor restoration must not reveal Editor before the single-pane workbench is restored: restored tabs fire onWillOpenEditor during startup before lifecycle/profile restoration settles. In SinglePaneWorkbench.revealEditorOnOpen, if !isRestored() and Editor is persisted hidden, return without revealing; after restore, normal user opens still reveal. Otherwise an Aux-only reload paints Editor briefly and the visibility profile closes it one frame later.

• Do not add a content-readiness handshake between the single-pane workbench and detail strategy: the layout node's visibility must not depend on openViewContainer completion or a markSidePaneContentReady-style API. Keep layout visibility and content restoration independently owned; solve startup presentation issues without coupling the workbench grid to asynchronous feature content.

• Persisted side-pane composition must not depend on tabs already existing: do not auto-hide Editor from onDidRevealSidePane merely because the editor group is empty during restore. Render the persisted Editor/Aux composition and let managed tabs restore afterward; the normal last-editor-close handler remains responsible for closing the pane after an explicit user close.

• Apply a side-pane composition by hiding undesired parts before showing desired parts: transitioning Editor-only → Aux-only must hide Editor first, then show Aux. Showing Aux first creates a transient Editor+Aux composition that is visible during New Session restoration; the inverse transition similarly hides Aux before showing Editor. Keep the sequence inside editor-auto-visibility suppression.

• Same-type session navigation still restores the shared lifecycle profile: Existing→Existing and New→New resource switches can transiently empty the editor group and hide Aux while working sets/tabs restore. Capture the one outgoing type profile, reapply it on every resource switch, ignore transient Aux hides, and reassert an aux-visible profile when content returns. Do not create per-session view-state entries.

• A draft submitted while Quick Chat is active must not seed profiles from the suppressed layout: Quick Chat intentionally hides both parts. Exclude transitions spanning Quick Chat from foreground-submit detection; when leaving Quick Chat, apply the already-saved Existing profile rather than capturing the hidden effective state into New and Existing.

• No active session during startup means preserve detail layout, not hide it: SinglePaneDetailPanelStrategy._computeDetailTarget runs after the workbench reaches Restored but before restoreVisibleSessions() finishes. Returning Hidden there closes persisted Aux; SinglePaneWorkbench._onWillHideAuxiliaryBar then reveals Editor, producing the reload flicker. Return Preserve until an active session exists; quick chats and real empty-session targets can hide once their identity is known.

• Restoring an Editor-visible profile from Quick Chat must not reveal Editor into a fully closed empty group: onDidRevealSidePane normally hides Editor while the group is empty, which races managed-tab recreation and leaves the pane closed. Skip that empty-pane guard while _isRestoringSessionLayout; do not stage the restore through a temporary auxiliary-bar reveal, because restoring saved editor-content width while Details is temporarily visible adds the detail width to the grid node and leaves the side pane wider after Details is hidden.

• An aux-visible profile restored from Quick Chat must survive the transient empty editor group: reveal the aux bar before Editor so saved editor-content width is reconstructed with the detail width, then keep an aux-restore pending while the main group is empty. Reassert aux visibility on the deterministic editor-group content signal; the detail strategy may hide it after the synchronous restore but before managed tabs settle.

• Entering Quick Chat must hide Editor before the docked aux bar: _persistedEditorWidth subtracts the detail width only while partVisibility.auxiliaryBar is true. Hiding aux first makes the subsequent Editor hide persist the combined editor+detail node width as pure editor width, so returning to an aux-visible Existing Session adds the detail width again and grows the side pane.

• Quick Chat activates before the outgoing editor working set is cleared: do not wait for mainPartEmpty on the initial Quick Chat transition before hiding Editor. Hide Editor immediately (then Aux) on entry so width capture sees Details visible; only subsequent Quick Chat re-evaluations use the empty-group guard, preserving a real editor deliberately opened inside Quick Chat.

• Per-session menu visibility must flow through scoped context keys, not widget DOM hiding or global active-session keys: toolbars evaluate when against their scoped IContextKeyService, while their pickers act on scoped ISessionContext. Expose provider-specific availability as an observable on ISession and publish it through setSessionContextKeys, so every visible session surface evaluates the same scoped state declaratively.

• The fixed Chats/Subagents picker does not need a group registry: contribute scoped chat actions to Menus.SessionConversations with stable group ids, then map those ids to local presentation metadata in SessionConversationsActionViewItem. Add a registry only when external/dynamic group extensibility is a real requirement.

• An active subagent inherits its parent conversation's picker scope: use activeChat.origin.parentChat for a tool-origin active chat, otherwise activeChat.resource, when filtering the flat Subagents group. Keep this local expression aligned with SessionActiveChatHasSubagentsContext; do not export a one-line helper from the session model.

• The Chats dropdown opens on the active conversation: pass a dynamic getInitialFocusActionId to the Action Widget dropdown. The active chat or subagent is an actual flat row and must be focused directly; do not mark rows checked merely to obtain initial focus.

• The Chats picker must explain grouping and progress (#329176) without repeating quiet defaults: the existing Subagents group title names the separation, while the redundant top-level Chats header stays hidden. Every row uses the existing Sessions status icon; show text for New/In Progress/Input Needed/Failed, keep Completed visually quiet, and always include an accessible State: status description.

• A single first-level chat is omitted from the Chats dropdown: show only its active-chat Subagents group. Side chats count as first-level chats, so their presence retains the first-level list.

• Action Widget checkbox semantics come from checked, not a parallel flag: an explicit checked: true/false is a checkable item; omitted checked is ordinary navigation. Do not add an isCheckable opt-out—the duplicate state can drift and is unnecessary for chat/subagent actions.

• Do not add Action List header ARIA-label branches when headers retain separator semantics: title-only group headers already render visually and are exposed as separators by the accessibility provider. Add custom header labels only when the header role/semantics intentionally change.

• Custom Sessions toolbar renderers use IActionViewItemService registration: register submenu renderers by (owning menu, submenu id) and let MenuWorkbenchToolBar resolve them before its generic fallback. Do not hardcode a Sessions-specific submenu check inside a part's actionViewItemProvider.

• Action Widget navigation items must omit ARIA checked state: when an action's checked is undefined, IListAccessibilityProvider.isChecked must also return undefined, not false; otherwise a menuitem incorrectly receives aria-checked="false".

• Action List initial focus is one-shot: consume initialFocusItemId during initial opening, then retain current focus or use the normal checked/first fallback. Never reapply the configured ID during filtering or later focus() calls, which would override user navigation.

• Explicit resource scopes must carry their owner and announce eligibility changes: never bind a plan/file to the globally active session because multiple sessions can render concurrently. Pass the owning session resource into registration and fire the scope-change event when the binding is added or removed so already-open editors refresh.

• Per-editor overlay actions must carry editor command context: an overlay can be invoked from an inactive split group, so resolving commands from the globally active editor can mutate the wrong resource. Set the toolbar context from its owning group and resolve it through resolveCommandsContext.

• A single-file diff layout toggle must target the resource-owning live control and disable adaptive inline fallback: the configured renderSideBySide value can be true while useInlineViewWhenSpaceIsLimited keeps the actual editor inline, making a setting-only toggle appear broken. Match the forwarded resource across visible TextDiffEditor panes (or use the active pane when no resource is forwarded), persist its modified model resource, apply both renderSideBySide and useInlineViewWhenSpaceIsLimited: false, and derive the menu state from diffEditorInlineMode rather than configuration.

• Single-file diff input identity and renderer capability need separate context keys: a DiffEditorInput can render through text, binary, or custom editor panes, so actions that apply to the owning Changes detail must gate on the input while text-layout actions gate on TextCompareEditorActiveContext. Reusing the text-pane key for both silently drops input-level actions on binary/custom fallbacks.

• Extension-host webview identity lives in providerId, not only viewType: dynamic webview panels use an internal prefixed viewType (for example mainThreadWebview-markdown.preview) and keep the contributed id in WebviewInput.providerId. Classify contributed webviews using providerId as well as direct/internal viewType, and model both fields in tests.

• Keep validation proportional to the change: once focused tests cover a small correction, do not chain repeated reviewers or broad suites unless a concrete failure warrants escalation.

• Use one side-pane state type and keep the default on the workbench layout: ISidePaneState contains { editor, auxiliaryBar }; overall visibility is derived when needed. Workbench.toggleSidePane() remembers and restores raw editor/aux visibility; when no state was previously captured it uses _defaultSidePaneState (base = Editor+Aux, SinglePaneWorkbench = Editor-only). BaseLayoutController listens on did only to filter the restored/default state against available editors and aux containers; do not reintroduce a controller default hook.

• Keep the side-pane toggle lifecycle in one method: Workbench.toggleSidePane() owns will-event emission, un-maximize preparation, visibility memory/transition, did-event emission, focus transfer, and the final visibility return. Do not split this linear lifecycle into _runSidePaneToggle / _toggleSidePane helpers; the ordering is easier to audit when it remains contiguous.

• A side-pane toggle needs one explicit settled reveal, with natural per-part reveals suppressed: setEditorHidden(false) / setAuxiliaryBarHidden(false) naturally notify on the first visible part, which is too early for listeners that must inspect/filter the full restored composition. The toggle passes skipSidePaneReveal: true explicitly to both reveal setters; after all parts are applied, toggleSidePane() invokes _onSidePaneRevealed() once. Avoid hidden toggle-state guards in the reveal hook. Keep exact-once test coverage so the explicit call cannot become a duplicate.

• Remembered and default side-pane compositions must share the same editor/aux-only type: type _sidePaneStateBeforeHide and _defaultSidePaneState as the same ISidePaneState editor/aux composition. Overall visibility is derived and must not be redundantly stored.

• Expose completed side-pane state on did-toggle, not will-toggle: onWillToggleSidePane remains Event<void> for pre-transition suppression. onDidToggleSidePane carries { before, after }, each with { editor, auxiliaryBar }, so consumers can distinguish collapse versus reopen and preserve pre-toggle aux visibility without side-channel fields.

• Do not record a side-pane collapse from the will event: will fires before the UI transition and only establishes _togglingSidePane. Record from the did event after verifying before was visible and after is hidden; the did payload preserves the pre-toggle aux visibility needed for collapse semantics.