Agent OS instance switcher + managed connection profiles

Context

Operator, live session 2026-08-18: FM should configure WHICH Agent OS instance it connects to — "right now to our dockerized local version on this machine, but it could be a cloud based deployment." The connection DATA layer already shipped its first leg: #16742 (C1 connection broker — profile identity contract, credential custody; session-only custodian executable via #17181 / PR #17176). What exists nowhere: the operator-facing UX for holding SEVERAL configured instances, seeing which one the cockpit is bound to, and switching.

The Problem

The cockpit renders one implicit instance. The spine banner speaks about "the fleet server" as if there were exactly one; connection profiles exist as a contract with no surface. An operator running the local dockerized composition plus a remote deployment cannot (a) see which instance the truth on screen belongs to, (b) switch, (c) manage endpoints and credentials per instance. Instance identity is the ROOT CONTEXT of every cockpit surface — fleet, activity, memories, tasks, diagnostics are all instance-relative — so its absence is an information-architecture gap, not just a missing form.

Sharpened 2026-08-18 (operator, live session — the seat-machine reality): on a machine that hosts only AGENT repo clones, there is NO operator-owned environment to carry an operator PAT — every checkout's forge identity is a seat account, and the env-var journey does not exist for the person at the keyboard. The FM UI is therefore the ONLY viable credential entry path for an operator on a seat machine. Credential entry through this surface is the operator's PRIMARY onboarding act, not an edge case of instance management: without it, every send impersonates a seat (the exact #17310 incident class, now detected but not curable in-product). Per-forge reality included: a GitHub PAT for a GitHub-planed instance, a GitLab PAT for a GitLab-planed one — the subject comes FROM the credential (no username field; the token proves the name), riding the forge-generic admission (#16736).

The Architectural Reality

• apps/agentos/fleet/connectionProfiles.mjs (C1 leg 1, PR #17176): normalizeFleetEndpoint, deriveFleetProfileId, createFleetProfile, isStaleProfile/rehydrateProfile — the profile record IS the instance record; credentials never enter Body-readable state (the Option-D falsifier).
• apps/agentos/view/Viewport.mjs top chrome toolbar (logo · title · theme switch) — the switcher's natural home per the #17269 navigation model.
• Spine banner + reconnectFleet (apps/agentos/view/fleet/FleetCockpit.mjs) — today's single-instance connection-state UI; #16744 (C3) extends its vocabulary with remote states.
• D#16720 (closed, graduated): FM-as-client — FM never runs a plane, FM connects; a remote instance is the same client path with a different endpoint + PAT custody.

The Fix (design-first)

1. Instance switcher in the top chrome: bound instance name + state dot; menu lists configured profiles; switching rebinds the cockpit through the C1 custody path; the banner narrates the transition in #16744's vocabulary.
2. Manage-instances surface (Settings-class, deliberately NOT Accounts — accounts are agent identities, instances are connection targets; mixing them muddies both): profile CRUD over the C1 contract, per-custodian affordances (session-only today; Electron-main and env-indirection legs render honestly as unavailable until #16742 legs 2–3 land), per-profile health probe.
3. Scope naming: instance-scoped surfaces reference the switcher as the one scope authority.

Acceptance Criteria

• Design sketch (§04-consistent) for switcher + manage surface posted on the ticket BEFORE implementation; the sketch is the PR's scoring contract, its review landing no later than the PR review. (Resequenced 2026-08-18 pre-implementation, maintainer call on the merits: the §06 design bar now EXISTS as the shipped contract — it did not when spec-first-strict was written for #17263 — the sketch is posted (IC_kwDODSospM8AAAABPbvEwg) and review-routed (Grace, 16:02Z), and the same seat reviews sketch and PR, so a strictly-before gate would park the lane on ceremony. The operator holds no gate here (influence ≠ authorship, corrected on the sketch comment). Original wording: "reviewed BEFORE implementation (spec-first gate, #17263 lane)".)
• Switcher renders the bound profile + connection state; switching rebinds through the C1 custody path without a reload; the banner narrates the transition.
• Manage surface: create/edit/retire profiles over connectionProfiles.mjs ONLY — no second storage; no credential in Body-readable state (the Option-D falsifier holds).
• The operator PAT-entry journey works end-to-end in the UI (the seat-machine primary path): enter a forge PAT for an instance → it reaches the serving transport through the authenticated wire (the connectTenant lifecycle-write class is the existing skeleton; the read half stays descriptor-only, never a credential) → the session re-establishes as the credential's subject → the #17310 conflation marker clears as the visible proof. Custody per the available custodian, named honestly: session-only today (re-entry per session is the honest cost until #16742 legs 2–3 land a durable custodian).
• Local-composition and a remote endpoint both configurable; unreachable/auth-refused instances render #16744's reason-carrying states, never a generic offline.
• Instance-relativity is explicit: switching swaps fleet/activity/memories coherently; no cross-instance data bleed. Torn-out windows follow-by-construction (same heap, per-call bridge resolution, same generation fences) and carry the instance label in document.title — scope as a per-window fact. (Clause added 2026-08-18 per the §7 gate decision on the review thread.)

Out of Scope

The custodian legs themselves (#16742 legs 2–3) · remote-state banner vocabulary (#16744) · sharing/grants (#16745) · deployment provisioning of remote instances.

Decision Record

Optional: D#16720 closing ledger; #16747 (D1 ADR, open). Decision Record impact: aligned-with the D#16720 graduation; none new.

Related

Epic #14560 (parent) · #16742 (profiles = the data layer) · #16744 (state vocabulary) · #16745 (grants pane) · #13015 (FM MVP epic anticipates the pane lane) · #17269 (navigation model: top-chrome placement) · D#16720 (topology authority) · #16736 (forge-generic PAT admission) · #16740 (credential-class ledger) · #16738 (operator principal class) · #17310 (the conflation incident this journey cures).

Live latest-open sweep: latest 20 re-checked 2026-08-18T08:15Z, no equivalent; A2A herd window clean (one unrelated engine claim #17327).

Origin Session ID: ca3c67ac-a3d6-4e93-98e0-c5f7f65011ee

Retrieval Hint: query_raw_memories("agent os instance switcher connection profiles cockpit root context")