Docking auto-hide: persist collapsed item state

Context

Epic #13158 names auto-hide / pin sidebars as the next QT-parity docking polish gap after the #13030 foundation. Current dev already has the dock-zone model, semantic operation executor, split/tab adapter, drag preview renderer, and splitter resize affordance. The remaining auto-hide gap is narrower than a full UI leaf: the persisted model reserves pinnable and pinned, but it has no committed collapsed/auto-hidden item state for a future sidebar renderer to consume.

Release classification: post-release harness-polish leaf — not release-blocking.

Freshness / duplicate evidence before filing:

• Live latest-open sweep: checked latest 20 open issues at 2026-06-14T18:53Z; saw #13247 as a standalone docking example, #13158 as the parent epic, and no auto-hide/pin state leaf.
• Exact open sweep: dock auto-hide pin autoHidden pinned returned no open issue match.
• Exact closed sweep: dock auto-hide pin autoHidden pinned returned no closed issue match.
• Closed polish sweep: interactive splitter resize is already covered by #13159 and #13206, so this leaf deliberately does not reopen resize work.
• A2A in-flight sweep: latest 30 messages at 2026-06-14T18:53Z had no overlapping [lane-claim] / [lane-intent] for docking auto-hide/pin state.
• Knowledge Base semantic sweep was attempted and failed with Knowledge Base is not available: Failed to access collections; live GitHub and local source/docs are the authority for this filing.

The Problem

DockZoneModel can persist item pin state, but the model cannot yet distinguish "unpinned but visible" from "auto-hidden/collapsed to an edge affordance." A future auto-hide sidebar renderer needs a JSON-only committed state bit and a semantic operation that changes it without writing runtime hover/open geometry into the saved layout.

Without this leaf, the next UI implementation would either invent ad-hoc state outside dockZone.v1, overload pinned: false, or store runtime-only hover/open details in persistence. All three would violate the existing contract boundary.

The Architectural Reality

• learn/agentos/HarnessDockZoneModel.md already documents pinnable, pinned, and the deferred auto-hide/pin capability from #13158.
• src/dashboard/DockZoneModel.mjs owns finite-schema validation, JSON-only saved layout wrapping, and semantic operations such as setItemPinned.
• test/playwright/unit/dashboard/DockZoneModel.spec.mjs is the focused contract test location for persisted model invariants and operations.
• Auto-hide runtime hover/open geometry belongs to a later renderer. This ticket is only the persisted semantic state and operation seam.

The Fix

Add a minimal committed auto-hide state to neo.harness.dockZone.v1 item records and route updates through DockZoneModel:

• allow an optional JSON boolean item field for the collapsed/auto-hidden state;
• validate the field during model validation, saved-layout creation, and restore;
• add a semantic operation to set/clear that state without mutating caller input;
• keep pinned: true and collapsed auto-hide state mutually coherent, so a pinned-open item cannot remain serialized as collapsed;
• update the dock-zone contract document to name the field, operation, and invariant;
• add focused unit tests for valid toggles, fail-closed invalid payloads, saved-layout validation, and pinned/auto-hide coherence.

Contract Ledger Matrix

Decision Record impact

Aligned with ADR 0020 and the #13030/#13158 docking roadmap. No ADR amendment required; this stays in the existing src/dashboard/ dock-zone model layer and does not introduce a core src/layout/Dock primitive.

Acceptance Criteria

• DockZoneModel supports a JSON-only committed auto-hide/collapsed item state through a named semantic operation.
• The model rejects non-boolean auto-hide state and any pinned-open/collapsed saved-layout incoherence fail-closed.
• Pinning an item open cannot leave the persisted item collapsed/auto-hidden.
• The dock-zone contract document names the field, operation, and serialization boundary; runtime hover/open geometry remains explicitly out of scope.
• Focused dashboard unit tests cover operation success, invalid payload rejection, saved-layout create/restore validation, and pin/auto-hide coherence.

Out of Scope

• Rendering collapsed edge rails, hover popouts, or pin buttons.
• Wiring auto-hide to DockPreview, DockSplitter, SortZone, or live pointer events.
• Named perspectives store/switcher work.
• Grouped tab drag or tab overflow menu work.
• Any partner-specific layout preset.

Avoided Traps / Gold Standards Rejected

• Overload pinned: false as collapsed — rejected because unpinned-but-visible and auto-hidden/collapsed are distinct states.
• Persist hover/open geometry — rejected by the JSON-first persistence boundary; runtime hover and target rectangles stay out of dockZone.v1.
• Bundle UI polish now — rejected because #13158 asks for one-PR leaves; this leaf creates only the model seam a later UI leaf can consume.

Related

Parent: #13158 Foundation: #13030 Related: #13159 Related: #13206

Origin Session ID: unavailable after harness restart / compaction; current turn is recorded via Memory Core.

Handoff Retrieval Hints: search for DockZoneModel setItemPinned autoHidden auto-hide #13158, neo.harness.dockZone.v1 item pinned collapsed state, and HarnessDockZoneModel auto-hide pin sidebars.