Whole-stack reintegration and the vessel close policy

Context

Epic #15239 leaf G4 — beat 5 of the five-beat story: grab the merged stack in a popup, drag it back into main, previews light, drop commits, the emptied popup closes itself. Implements the #15240 outcome machine's terminal effects (D#15204 OQ5b [RESOLVED_TO_AC], cycle-4) and owns OQ5a as its first design task. Unowned — self-select.

The Problem

Four gaps: (a) transferNode() (ADR 0029 §2.4, landed) rejects workspace ROOTS — a whole popup stack has no source projection today (OQ5a, this leaf's first design decision: stack source projection vs the root rejection; additive on dockLayout.v2 only, per the epic's revalidationTrigger); (b) addTab APPENDS — exact-position reintegration needs stored-index capture/restore (cycle-4c verified, DC_kwDODSospM4BDXXd); (c) vessel close policy is undesigned; (d) ADR 0029 §2.2 placement hints are a named remaining obligation.

The Architectural Reality

• The #15240 outcome machine governs every terminal: source cleanup + empty-vessel close ONLY after COMMITTED_TARGET; reject/no-preview restores the source with zero model mutation; model commit precedes window close — a close failure can neither roll back the commit nor double-reintegrate.
• Container.onWindowDisconnect() may reintegrate unless its runtime flags are exact (falsified risk, Step-Back ✗4) — the close path must be idempotent against it.
• Empty-workspace registry disposition (Step-Back ✓7): closing a vessel unbinds a render target; whether the emptied workspace-set entry is retained or retired is named SEPARATELY from closing its OS window; recovery stays semantic through fallbackTarget.
• Blocked-by: #15246 (G3's workspace-set + claims are the substrate a stack transfer commits through).

The Fix

One PR: the stack source projection (OQ5a design + implementation, additive hints on dockLayout.v2 with migration + fail-closed tests if any schema field is added), stored-index capture/restore for exact return, the vessel close policy per the outcome machine, and the §2.2 placement-hint layer for the return drop.

Acceptance Criteria (the graduated OQ5a/OQ5b contracts)

• A whole popup stack (multi-item node subtree) drags back into main as ONE gesture and commits atomically — both documents mutate in one executor transaction (commit-or-neither), per the §2.3/§2.4 semantics.
• OQ5a resolved in-leaf: the stack source projection design is documented in the PR (the descriptor shape additive on dockLayout.v2; any schema addition ships migration + fail-closed tests atomically).
• Exact-position return: stored-index capture at detach, restore at reintegration (addTab append semantics compensated); witnessed round-trip (detach → return → identical topology AND order).
• Vessel close: only after COMMITTED_TARGET; commit-precedes-close witnessed; a simulated close failure leaves the committed document intact with no double-reintegration (the onWindowDisconnect idempotency pinned).
• The emptied workspace-set entry's disposition (retained vs retired) is explicit and witnessed separately from the OS-window close.
• §2.2 placement hints render on the return drop (the main window's affordances show WHERE the stack lands) through the shared #15207 consumer.

Out of Scope

Claim arbitration (G3, consumed) · tear-out (G1/G2) · coordinator teardown residue (its own leaf) · the keyboard path (its own leaf).

Related

Parent #15239 · blocked-by #15246 · D#15204 (OQ5a/OQ5b; Step-Back ✗4/✓7) · #15240 (outcome authority) · #15193 (transfer guards) · cycle-4c deposit DC_kwDODSospM4BDXXd.

Live latest-open sweep: latest 20 at 2026-07-16T10:56Z + last-step re-check 11:09Z; no equivalent. A2A claim sweep: no competing claim.

Origin Session ID: c5d7cd6b-4e01-45fd-aa59-5ccbc0e5f091 Retrieval Hint: "G4 whole-stack reintegration vessel close stored-index transferNode root OQ5a"