Switchboard is being designed as a persistent user view over the provider-native coding-agent sessions it starts. Its target primary interface is a tmux-resident navigator beside the active native provider pane; direct single-pane mode remains available when no Switchboard UI is wanted. The new design gives Switchboard project/workstream navigation, managed-filesystem ownership, and tmux presentation while Codex and Claude Code continue to own conversation history, native thread names, composer, lifecycle workflow, settings, and terminal UI. The Phase 7H implementation now provides that navigator, explicit native-rollover reconciliation, background result attention, and capability-gated native-history Peek for fresh, Switchboard-created state; it is not installed into or adopted by the user's normal workflow.
This repository is frozen as a Python reference checkpoint after Phase 7H. It preserves the executable prototype, isolated evidence, and product contracts for a clean Rust successor; it is not a viable, supported, adopted, or installable product release. No Phase 7I work should begin in this repository.
See the Python Phase 7H Reference Checkpoint for the decision, retained evidence, known limitations, and Rust handoff.
Switchboard has not reached a viable or adopted product release. Core 0.4.0
is a Phase 7 checkpoint identity, not a production release. The user's normal
workflow remains native Codex, Claude Code, and tmux.
Phases 7B through 7H are accepted: Config v4, generation-4/schema-v2 state,
strict fresh initialization/reset, thread/workstream records, installed Codex
contract fingerprinting, and a recoverable explicit provider-only action
engine exist in the clean _v4 runtime.
Phase 7E checkpoint, managed-worktree, workstream fork/start, private-surface, and conservative-retirement internals are implemented with deterministic recovery coverage. Its installed watched composition passed on 2026-07-25: while Y continued in source A, Switchboard forked the explicitly selected completed turn X and Checkpoint X into B, delivered one Z turn, preserved both native result tips, isolated the worktrees, and removed every private process and artifact. The control clients and native panes share one private Codex App Server Unix WebSocket; fork admission deliberately carries no Y observation authority. The pre-7F product-host review selected a narrow tmux-based Switchboard navigator, with Herdr as UX reference and Agent Deck as implementation reference.
That accepted checkpoint-coupled fork is retained as stronger technical evidence, not the v1 product default. The current 7F design instead forks the provider conversation through completed turn X while creating the destination worktree from the Project's configured default branch. It records and displays those two lineages separately and leaves merge/rebase/cherry-pick or other synchronization to the user or agent.
The accepted 7F implementation prioritizes canonical native thread names,
one-action focus/resume, and a minimal resident navigator. Native /new,
/clear, /fork, Plan choices, /rename, prompting, models, permissions,
and history remain the normal workflow. Switchboard adds out-of-band interrupt
and composes independent/forked worktrees without a session wizard, prompt box,
mandatory name, or competing thread title. V1 manages only threads and
workstreams started through Switchboard; arbitrary existing-session onboarding
is deferred. Independent work starts in a native-origin empty composer on a
generation-private Codex App Server. Completed-prefix reads and forks use
Codex's persisted-history semantics, matching native resume behavior. The
private tmux runtime creates no placeholder window, respects NO_COLOR,
supports click-to-select navigation, and shares the exact provider environment
needed for live active/result-ready status. It uses short generation-private
socket paths. Exact shutdown stops only the confirmed generation's private
tmux and App Server processes, marks their surfaces lost, and preserves
provider history, repositories, and worktrees.
The accepted 7G implementation follows native /new, /clear, /fork, and
Plan clear context and implement without creating a competing lifecycle.
One recently observed exact same-cwd destination appears as an unbound
candidate; a confirms it in the navigator and z abandons it. Confirmation
atomically rotates the Workstream and live Surface binding but never submits
provider input. Ordinary implement this plan remains in the current
thread. Installed Codex exposes an empty /new or /clear identity through
stable listing only after its first native user turn; no global hook is
installed to hide that provider limitation.
The accepted 7H implementation records exact background-result attention
without stealing focus or adding provider traffic. The navigator displays
native source/current identity, ancestry, activity, confirmed transition, and
attention metadata. Native history and resume remain canonical. An explicit
p/thread peek action may open a historical thread behind a tested
input-dropping PTY; the normal current Surface remains interactive and one
Focus action closes Peek and returns to its byte-stable tip.
The installed wheel contains no _v3 runtime, legacy reader, Frame
compatibility layer, global hooks, automatic native-rollover authority,
arbitrary existing-session adoption, or normal-workflow installation.
The direct CLI and resident navigator operate only on explicit fresh roots:
swbctl --config-root ROOT --state-root ROOT init --config CONFIG_V4
swbctl --config-root ROOT --state-root ROOT project start REPOSITORY
swbctl --config-root ROOT --state-root ROOT attach
swbctl --config-root ROOT --state-root ROOT workstream start --project PROJECT
swbctl --config-root ROOT --state-root ROOT workstream fork --workstream WORKSTREAM
swbctl --config-root ROOT --state-root ROOT workstream interrupt --workstream WORKSTREAM
swbctl --config-root ROOT --state-root ROOT workstream focus --workstream WORKSTREAM
swbctl --config-root ROOT --state-root ROOT workstream rollover-confirm \
--workstream WORKSTREAM --candidate CANDIDATE
swbctl --config-root ROOT --state-root ROOT workstream rollover-abandon \
--workstream WORKSTREAM --candidate CANDIDATE
swbctl --config-root ROOT --state-root ROOT thread rename --thread THREAD NAME
swbctl --config-root ROOT --state-root ROOT thread peek --thread THREAD
swbctl --config-root ROOT --state-root ROOT action reconcile REQUEST
swbctl --config-root ROOT --state-root ROOT shutdown \
--confirm-generation GENERATION
swbctl --config-root ROOT --state-root ROOT reset \
--confirm-generation GENERATION --config CONFIG_V4
The _v3 source remains in the repository only as historical evidence while
the loop proceeds. It is outside the built artifact and is never imported by
_v4.
Design and operations:
- Proposed Thread and Workstream Redesign (non-normative; superseded by the approved Phase 7A contract)
- Thread and Workstream Redesign Decision
- Thread and Workstream Redesign Review
- Thread and Workstream Redesign Roadmap
- Terminal-first Product Landscape (current research and pre-7F product gate)
- Herdr Assessment and Phase 7 Implications (dedicated source audit; no integration approved)
- Phase 7A Production Contract
- Phase 7A Contract Matrices
- Phase 7B Acceptance
- Phase 7C Acceptance
- Phase 7D Acceptance
- Phase 7E Acceptance Status
- Phase 7F Native-Workflow Navigator Acceptance
- Phase 7G Native Rollover Acceptance
- Phase 7H Result, Attention, and History Acceptance
- Python Phase 7H Reference Checkpoint
- Agent Switchboard Design
- State and Control-Turn Contract (superseded Phase 6 reference)
- View and Frame Workflow (superseded Phase 6 reference)
- Runtime Operations and Safety
- Phase 6 Clean-Break Plan
- Phase 6F Acceptance
- Phase 6F.2 Acceptance
- Phase 6E.1 Acceptance
- CutoverBundle v1 and Activation
- Deferred Cross-host Usage Discovery
Historical 0.2 records remain outside the installed package under
docs/archive/0.2.
The completed Phase 6E activation retrospective is retained under
docs/archive/0.3.
Switchboard is licensed under the MIT License.