sessions

name	sessions
description	Agents window architecture — covers the agents-first app, layering, folder structure, chat widget, menus, contributions, entry points, and development guidelines. Use when implementing features or fixing issues in the Agents window.

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

Document	Path	When to read
Layer rules	src/vs/sessions/LAYERS.md	Before adding any cross-module imports. Defines the internal layer hierarchy (core → services → contrib → providers) with ESLint-enforced import restrictions. Key rule: contrib/* must NOT import from contrib/providers/*.
Layout spec	src/vs/sessions/LAYOUT.md	Before changing any part, grid structure, titlebar, or CSS. Documents the fixed grid layout (Sidebar | ChatBar | AuxiliaryBar), part positions, the modal editor system, per-session layout state persistence, and the titlebar's three-section design.
Layout controller spec	src/vs/sessions/LAYOUT_CONTROLLER.md	Before changing LayoutController or per-session layout state. Details how the auxiliary bar, panel, and editor working sets are captured/restored when switching sessions, multi-session suppression, the auto-reveal-on-changes flow, workspace-folder ordering, and storage/migration.
Sessions spec	src/vs/sessions/SESSIONS.md	Before changing session/provider interfaces or data flow. Covers the pluggable provider model (ISessionsProvider → ISessionsProvidersService → ISessionsManagementService), ISession/IChat interfaces, observable state propagation, workspace/folder model, and session type system.
Sessions list spec	src/vs/sessions/SESSIONS_LIST.md	Before changing the sessions sidebar list. Covers the tree widget (WorkbenchObjectTree), renderers, grouping (workspace/date), filtering (type/status/archived/read), pinning, read/unread state, workspace capping, mobile adaptations, storage keys, and registered actions.
Mobile spec	src/vs/sessions/MOBILE.md	Before adding any phone-specific UI. Covers the mobile part subclass architecture, viewport classification (phone < 640px), MobileTitlebarPart, drawer-based sidebar, MobilePickerSheet, view/action gating with IsPhoneLayoutContext, and the desktop → mobile component mapping.
AI Customizations	src/vs/sessions/AI_CUSTOMIZATIONS.md	Before working on the customization editor or tree view. Documents the management editor (in vs/workbench) and the tree view/overview (in vs/sessions/contrib/aiCustomizationTreeView).

Common Pitfalls

• Wrong menu IDs: Never use MenuId.* from vs/platform/actions for Agents window UI. Always use Menus.* from browser/menus.ts.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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 fixed at adapter construction — every construction path must carry _meta: AgentHostSessionAdapter resolves its session-kind (QuickChatSessionKind vs WorkspaceSessionKind) once, from readSessionWorkspaceless(metadata._meta) in the constructor; _computeWorkspace() and isQuickChat delegate to that fixed kind and cannot be flipped by a later update/setMeta. So the _meta.workspaceless tag must be present in the metadata passed to every adapter-construction path: _refreshSessions()/listSessions and the live _handleSessionAdded(summary) notification (carry summary._meta). Dropping _meta on either locks a committed quick chat into WorkspaceSessionKind and leaks its <userHome>/.copilot/chats/<id> scratch dir as a workspace (breaking the archive-on-delete fallback, list badges, changes/files). On the host, CopilotAgent.listSessions() must re-emit _meta.workspaceless from persisted copilot.workspaceless metadata (mirroring getSessionMetadata) 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.
• 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 derives it from readSessionWorkspaceless(_metaObs); 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 copilot.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.)

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.

• Default/main chat title persistence differs per provider — don't unify them: For the agent host, the default (main) chat title is independent of the session title (AgentHostSessionAdapter._defaultChatTitleOverride, persisted on the host as customChatTitle:<defaultChatUri>); it must be seeded back on restore via restoreSession/_ensureDefaultChat (mirroring _restorePeerChats), or it reverts to the session title after a process restart / idle eviction. For the local chat sessions provider (localChatSessionsProvider), the primary chat and the session intentionally share one _title observable, so renaming the first/main chat updates the session title live — this is by design; do not "fix" it to be independent. Only additional (non-primary) local chats have their own title.

• 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. A static (non-interactive) action-item label (e.g. the single-pane diff-stats label) that should show no hover affordance must override with 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.

• A managed placeholder editor must never reveal the docked editor content: the empty Files placeholder tab (EmptyFileEditorInput) activates as a side effect of closing another tab (e.g. the Changes tab), firing onWillOpenEditor before it is in the group model. The workbench onWillOpenEditor reveal handler must skip revealing for that placeholder (check e.editor.typeId === 'workbench.editors.agentSessions.emptyFile' — a literal, since src/vs/sessions/browser/* is core and must not import the contrib EmptyFileEditorInput). Do NOT use a broad "editor already in group -> skip" rule: that also stops a hidden editor from revealing when the user re-opens an already-open real file. Extract the handler into a named method (_handleWillOpenEditor) so it is unit-testable via Reflect.get(Workbench.prototype, ...).

• Gate single-pane editor-title actions on MainEditorAreaVisibleContext: every single-pane (config.<DOCK_DETAIL_PANEL_SETTING>-gated) editor-title menu item (Maximize/Restore, Toggle Details, Hide Editor, Open in Modal) must include MainEditorAreaVisibleContext in its when so the whole action set disappears when the editor content is closed — the docked tab bar stays but its right-hand actions do not. 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: ChangesTabController shows the empty Files tab only when the editor area is closed OR no real (non-managed) editor is open; once a real file/diff is open in a visible editor area it removes the placeholder (and re-adds it when the area closes). Drive this off an autorun that also reads the editor-area visibility (observableFromEvent(onDidChangePartVisibility, () => isVisible(EDITOR_PART, mainWindow))) and an editor-change signal (observableSignalFromEvent(this, Event.any(onDidActiveEditorChange, onDidEditorsChange))), and keep the ensure/remove idempotent so it settles instead of looping. 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 must still be user-closable — remember user dismissals instead of blindly re-ensuring: ChangesTabController re-ensures the managed Changes/Files tabs on many signals (session state, editor visibility, editor changes). Without care this re-creates a tab the instant the user closes it, so the tab feels un-closable (the managed tabs are non-preview pinEditor, NOT sticky — they do have close buttons; the blocker is the re-ensure, not a missing button). Track user-initiated closes in a _dismissedManagedTabs set (via onDidCloseEditor, ignoring the controller's own closes tracked in an _internallyClosingEditors set) and skip ensuring a dismissed kind. Clear the set only on a session change or when the side pane is reopened from fully closed (edge-detected via a stored _sidePaneWasVisible), so closes stick within the session while reopening/switching re-populates (Scenario B).

• 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).

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

• Managed-tab reconciliation must run entirely under suppressEditorPartAutoVisibility(): ChangesTabController._syncChangesEditor closes stale managed tabs (e.g. a restored Changes tab whose session's workspace hasn't resolved yet on reload) before ensuring the current ones. If any close (esp. _closeInactiveChangesEditors) 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. Relatedly, the managed Files placeholder tab must NOT be auto-removed based on editor-area visibility (old Scenario 9 auto-remove) — that removal also emptied the group on reload; only remove it on an explicit user close (tracked via _dismissedManagedTabs).

• 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. Two bugs resulted: (1) the workbench handleDidCloseEditor docked branch saw an empty group and closed the whole side pane (reload/Cmd+N flicker: pane/Files-tab appears then vanishes); (2) ChangesTabController._handleEditorClosed recorded the external close as a user dismissal, poisoning _dismissedManagedTabs so the Files tab toggled on/off on alternate Cmd+N presses. Fix: _withSessionLayoutRestore (base controller) holds suppressEditorPartAutoVisibility() for the whole (async) restore only when isSinglePaneLayoutEnabled (OFF layout unchanged), so layout-driven closes never reach handleDidCloseEditor; and _handleEditorClosed ignores closes while layoutService.isEditorPartAutoVisibilitySuppressed() is true, so only a genuine user close dismisses a managed tab. Added isEditorPartAutoVisibilitySuppressed() to IAgentWorkbenchLayoutService as the shared "this close is layout-driven, not a user action" signal.

• 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.

• Single-pane detail/tab behaviour lives ON the layout controller, not in separate controllers or a shared service: SinglePaneDesktopSessionLayoutController 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: because everything is now one class, "is a session-switch restore in progress?" is just the base protected getter this._isRestoringSessionLayout (set by _withSessionLayoutRestore), so a restore-driven editor change never force-reveals the detail or dismisses a managed tab. The two sub-behaviours register in the _registerAuxiliaryControllers() base hook, deferred to LifecyclePhase.Restored so managed tabs reconcile on top of the restored editor group. The base controller gained IChangesViewService + IContextKeyService deps and a protected _editorGroupsService to support this (a subclass can't add DI ctor params without redeclaring all base params, so the 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). SinglePaneDesktopSessionLayoutController._syncForcedDetailTarget reveals a hidden detail ONLY when it was transiently hidden by a browser tab (_hiddenByBrowser), 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. The reopen default is layout-aware via the base _defaultReopenSidePaneParts() hook (base returns both parts; single-pane returns {editor:true, auxiliaryBar:false} for a created session and {editor:false, auxiliaryBar:true} for a new-session view). The detail is opened only via Toggle Details or restored per-session state. When changing this, update the [single-pane] ... file tab activation / [per-session detail] / reopen-default tests together — they encode the reveal semantics.

• Editor-title actions that only make sense with a restorable editor must also gate on EditorMaximizedContext.negate(): the single-pane "Hide Editor" action is meaningless while the editor area is maximized, so its when includes EditorMaximizedContext.negate() (in addition to MainEditorAreaVisibleContext + SinglePaneDetailChangesOrFilesActiveContext).

• 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.

• 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, SinglePaneDesktopSessionLayoutController._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.

• An auto-collapsed sessions list must be restored once the side pane is fully hidden: the single-pane responsive rule auto-collapses the sessions list to free width for a visible side pane (Toggle Details, opening a file). It must also restore an auto-hidden list when the side pane becomes fully hidden (both editor and aux bar closed) — e.g. switching to a quick chat (no side pane) — otherwise the list is left collapsed with nothing to make room for (bug: "sessions list closed even though the side pane is hidden"). Implement as an autorun in _registerResponsiveSidebar on an observableFromEvent(onDidChangePartVisibility, () => editorVisible || auxVisible) (the value-dedup is essential: hiding the sidebar itself doesn't change the computed side-pane visibility, so the pre-reveal auto-hide from opening an editor is never undone). Restore only when _sidebarAutoHidden is true, so a list the user closed manually stays closed.

• 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.

• 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.