design.md

Agent Switchboard Phase 7 Design

Date: 2026-07-25

Status: Phases 7A through 7H accepted; native-workflow navigator, attention, and capability-gated Peek implemented in isolated fresh state; no normal-workflow adoption

Target release: fresh 0.4.0 generation under development

The normative lifecycle and authority details are in the Phase 7A Production Contract and its machine companion. The Phase 7 roadmap is the implementation and authorization sequence.

Product Statement

Switchboard is a thin coordination layer around provider-native coding-agent workflows that it starts. It keeps a compact resident navigator beside the directly interactive native provider TUI. It helps the user identify, resume, rename, focus, interrupt, and branch Switchboard-managed work without replacing the provider's composer, history, settings, or ordinary lifecycle controls.

The target is not merely a native-looking interface. The provider's native workflow remains canonical:

• start and resume provider chats normally;
• use native /new, /clear, /fork, Plan choices, /rename, and history;
• type prompts in the native composer;
• choose models and permissions in the provider UI; and
• keep provider sessions useful when Switchboard is absent or broken.

Switchboard removes friction only where it can add real value:

• persistent discoverability across Switchboard-created projects and workstreams;
• one-action focus or exact native resume;
• native rename for an unfocused or background thread;
• out-of-band interrupt while another pane is focused;
• composition of a new native thread with an isolated Git worktree;
• composition of an exact provider conversation fork with a separate managed worktree from the Project's configured default branch; and
• durable recovery when a compound external action has an uncertain outcome.

Ownership Boundary

Concern	Canonical owner	Switchboard role
Conversation identity and transcript	Provider	Store an opaque binding and bounded lineage
Thread name	Provider	Read, display, and invoke the native rename operation
Composer, prompt submission, model, and permissions	Provider TUI	Never duplicate them in the default navigator
Project files, commits, and cross-workstream synchronization	Git/user	Resolve exact default-base commits; never manufacture or synchronize user commits
Managed worktree lifecycle	Switchboard	Create and retire only exact Switchboard-owned worktrees
Workstream relationship and focus	Switchboard	Persist grouping, attention, and presentation
Terminal rendering and interaction	Provider TUI and tmux	Place/focus panes without proxying terminal I/O

Provider UUIDs remain routing identity. The provider's persisted thread name is the canonical human-readable name and must also appear in native resume surfaces. Switchboard must not create a competing shadow thread title.

A Workstream may have an optional Switchboard label because it can contain more than one sequential provider thread. That label is grouping metadata, not the thread's name, and is never required to start or fork work.

Core Model

Host
  Project (one configured Git repository in v1)
    Workstream (one exclusively owned Git worktree)
      Task (one semantic attempt; conversation forks form a family)
        ProviderThread A -> B -> C

• A provider-native new/clear rollover creates another ProviderThread but keeps the same Task, Workstream, and Checkout.
• Starting unrelated work creates a new Workstream and managed Checkout from the Project's configured default branch without conversation ancestry.
• Forking creates a sibling Workstream whose provider conversation forks through one exact completed turn. Its independent managed Checkout starts from the Project's configured default branch; no matching filesystem-state claim is made.
• Resuming a provider thread never creates another ProviderThread record.
• For Switchboard-managed state, changing Git worktrees means changing Workstreams. A Workstream never spans or shares worktrees.
• V1 lists, resumes, and controls only threads and workstreams that Switchboard started or subsequently observed inside a Switchboard-managed surface. Importing arbitrary pre-existing native sessions is deferred.
• Switchboard state is disposable; provider histories and ordinary repositories are not.

Resident Navigator

The v1 navigator is deliberately narrow. It remains visible beside the native provider pane and shows:

• project and workstream grouping;
• the canonical native thread name;
• branch/worktree context;
• current, running, interrupted, result-ready, unavailable, or recovery state;
• source/current relationship during a transition; and
• last activity sufficient to choose what to resume.

Its primary actions are:

• focus or exact native resume;
• rename the exact provider thread;
• interrupt the exact active turn;
• start an independent workstream; and
• fork the selected completed conversation prefix into an alternative workstream.

Guarded retirement and recovery are secondary actions shown only when applicable. Native-binding reconciliation is internal, not a button. Same-workstream start-thread, exact checkpoint-coupled fork, prompt aliases, manager-owned Plan cutover, arbitrary existing-session onboarding, and historical peek are not primary v1 actions.

There is no session-creation wizard, model picker, prompt box, transcript view, mandatory workstream name, or attach-away manager mode.

The navigator honors NO_COLOR; otherwise it uses the managed terminal's color capability for selection and attention. Starting the first Workstream creates its provider window directly—there is no bootstrap placeholder window. Keyboard selection remains available, and a primary-button click on any rendered Workstream line selects that row. The navigator and provider panes receive the same managed provider environment so active and result-ready state can refresh without changing provider input.

Naming and Resume

The common workflow is one long provider thread. Switchboard therefore optimizes identification and return among its known threads rather than encouraging artificial thread rotation.

For Codex:

• /rename remains the normal in-TUI action;
• a navigator rename calls the capability-gated native thread/name/set operation against one exact ProviderThread;
• Switchboard reads the persisted name back before committing the receipt;
• rename creates no model turn and writes nothing into the transcript; and
• the same name must be visible from Codex's native resume workflow.

An unnamed thread may be displayed with temporary derived context such as project, branch, and last activity. That fallback is not persisted as a second thread name. Switchboard-created threads may remain unnamed until the provider or user names them; creation never requires a naming form.

Native provider history and resume remain canonical for Switchboard-known threads. The first release does not scan, import, focus, or take ownership of arbitrary provider sessions that were started outside Switchboard.

Native Thread Lifecycle

Codex /new and /clear both create a fresh provider chat while preserving the source history. /clear additionally clears the visible terminal/chat UI. They are A -> B transitions, not destructive mutation of A. V1 reconciles these actions only inside a Switchboard-started managed surface.

The provider performs native rollover and any native Plan-carried input. Switchboard observes the resulting exact identity and never duplicates that input. If trustworthy automatic adoption is unavailable, the provider action still succeeds normally; Switchboard shows a bounded unbound/recovery state and offers one explicit confirmation.

Installed Codex does not broadcast later TUI-owned thread starts on the stable observer connection. Switchboard therefore treats one recently created, same-cwd unknown identity as an observation only. It becomes visible after Codex materializes the first native turn, remains powerless until explicit confirmation, and is rejected if the managed Surface, source revision, cwd, ancestry, or Plan evidence no longer agrees. This does not import older or arbitrary sessions.

A same-workstream Start thread primitive remains useful internally and for future advanced clients, but it is not a primary 7F workflow. When the source is idle, native /new or /clear is simpler and more familiar.

Exact conversational prompt interception and a separate Implement selected plan fresh action are deferred. Native Plan clear context and implement remains canonical, while ordinary implement this plan continues in the current thread.

Independent and Forked Work

These are the two places where Switchboard intentionally composes native operations.

Start independent workstream

The default action:

1. uses the current Project;
2. resolves the Project's configured default_base_ref to one exact local commit;
3. creates a collision-free managed branch/worktree;
4. creates a new provider thread at that cwd; and
5. focuses its native composer.

The default navigator does not ask for an object ID, model, thread name, first prompt, or branch name. Selecting a source-workstream commit is deferred; v1 always branches from the configured Project default.

Fork workstream

The default action:

1. selects the last completed turn X visible when the user requests the fork;
2. resolves the Project's configured default_base_ref to one exact local commit M;
3. creates an isolated managed worktree at M;
4. asks the provider to fork the conversation through X at that cwd;
5. proves the provider prefix and the separately recorded filesystem base; and
6. focuses B's native composer.

Concurrent source turn Y is excluded from authority and destination lineage. No manager prompt is required. A future explicit client may supply one bounded first prompt, but the resident navigator does not replace the native composer.

The two lineages are intentionally independent:

conversation: forked from A through completed turn X
filesystem:   created from Project default base M

Switchboard does not claim that M contains the filesystem state discussed in X. Commits and uncommitted changes that exist only in source Workstream A are absent from B. The user or agent may later synchronize with ordinary Git operations such as merge, rebase, or cherry-pick; Switchboard performs none of them automatically.

Exact checkpoint-coupled filesystem fork remains a possible post-v1 enhancement. It is not a precondition or hidden default for Fork workstream.

Result Visibility, Attention, and History

A completed provider result remains the byte-stable pane tip until the next real user action. Background completion raises navigator attention and never steals focus or submits provider traffic.

Native provider history and resume remain canonical. The navigator shows bounded names, identities, ancestry, and activity metadata without rendering a transcript.

Input-fenced native historical inspection is offered as an explicit Peek capability for the accepted Codex contract. It is independently capability-gated, not a replacement for normal provider resume, and disables itself if the exact input-dropping boundary cannot be established.

Safety and Failure Behavior

• One explicit user intent creates at most one semantic action.
• A destination receives at most one prepared first prompt when an advanced client explicitly supplies one.
• Unknown provider, pane, process, cwd, ancestry, commit, or response outcome fails closed into visible recovery.
• Hooks and provider events are evidence, never sufficient authority alone.
• Interrupt never claims filesystem rollback.
• Switchboard never commits, merges, rebases, cherry-picks, stashes, resets, fetches, pushes, or force-removes user work.
• Conversation-fork lineage and filesystem-base lineage are displayed separately and never presented as an exact checkpoint match.
• Dirty, shared, external, active, unmerged, or mismatched worktrees are not removed.
• Exact generation-confirmed shutdown stops only Switchboard's private tmux and App Server runtimes, marks their surfaces lost, and preserves provider histories, repositories, and worktrees.
• Normal tmux servers and provider sessions stay outside reset, repair, and test ownership.

Phase Boundary

Phases 7B through 7F established the fresh registry, Codex capability adapter, recoverable action engine, and exact provider/worktree fork composition. Those internals now back a narrow CLI and resident navigator over fresh, Switchboard-created state; they are not installed into the user's normal workflow.

Phase 7F replaced the checkpoint-coupled fork_task shape with the default-base fork_workstream contract and made native names, exact focus/resume, interrupt, independent start, and completed-prefix fork real. Independent start is native-origin: the TUI creates its empty thread on a generation-private App Server, then Switchboard reconciles exact launch/cwd/time evidence. Completed-prefix read/fork uses Codex's persisted history path, matching ordinary native resume.

Phase 7I combined acceptance, arbitrary existing-session onboarding, and normal-workflow adoption each require separate user authorization.