[architect] refactor: extract TerminalSession interface from Manager's eight terminal seam fields (pkg/agent, #5636 phase 1)

[kubestellar-hive]

Refactor

Claimed ground: src/pkg/agent/manager.go (Manager struct terminal fields + captureTmuxPaneForAgent, captureVisiblePaneForAgent, tmuxSessionHasAttachedClientForAgent, tmuxSendLiteralForAgent, tmuxSendKeysForAgent, sleepDuringPromptDismiss), src/pkg/agent/kick_logs.go (captureScrollbackForAgent, clearScrollbackForAgent), new src/pkg/agent/terminal.go + terminal_seams_test.go, and mechanical seam-assignment rewrites in 9 pkg/agent test files. Disjoint from all open hold-gated PRs (#5634 scanner escalation, #5628 docs, #5625 pkg/convergence/mutation, #5559 UPGRADE.md, #4032 proxy auth).

Phase 1 of #5636 (Manager god object). Manager carried eight ad-hoc nilable func fields — paneCapture, visiblePaneCapture, sessionAttached, sendLiteralForAgent, sendKeysForAgent, promptDismissSleep, captureFullLogFn, clearHistoryFn — that together formed an implicit terminal-IO contract, each with its own nil-guard and inline tmux fallback.

This names that contract:

• TerminalSession interface (terminal.go) with tmuxTerminal as the production impl; every method body is the previous fallback code moved verbatim from manager.go / kick_logs.go.
• Manager's 8 fields collapse to one terminal TerminalSession; nil ⇒ tmux via Manager.term(), so zero-value &Manager{} (used widely in tests) behaves identically.
• funcTerminal (test file only) is a per-method override fake with tmux fallback, preserving old unset-seam semantics; test assignments rewritten mechanically m.paneCapture = f → termSeams(m).capturePane = f.

No behavior change. go vet clean; full go test ./pkg/agent/ suite passes (269s).

Follow-up phases per #5636: credential/resolver grouping, nil-safe Hooks struct, file split.

Refs #5636

---

Filed by architect agent (ACMM L5 — hold-gated mode). Hold-gated: human review required.

— hive: agent=architect backend=copilot model=claude-opus-4-6

[github-actions]

Changelog: this PR changes code but does not touch CHANGELOG.md.

If it is user-visible — a feature, a fix an operator would notice, a
security change, a migration, a deprecation, or anything breaking —
please add a line under ## Unreleased. If it is a refactor, a
test-only change, or dependency churn, no entry is needed and you can
ignore this.

This is a reminder, not a gate; it never blocks a merge.

[clubanderson]

Reviewed with specific attention to pkg/agent Manager's locking history. Approving — OK to merge.

Verified interface extraction only, no behavior or lock-ordering change:

• Every tmuxTerminal method body is a verbatim move of the previous inline fallback from manager.go / kick_logs.go (compared line by line: CapturePane, CaptureVisiblePane, SessionAttached including its three fail-open returns, SendLiteral, SendKeys, Sleep, CaptureFullLog including the -J/-S/-E flags and error wrap, ClearHistory).
• No new locking anywhere: Manager.term() reads m.terminal exactly as the eight old nilable func fields were read (no m.mu acquisition), tmuxCmd takes no lock, and no TerminalSession method touches m.mu — so nothing changes for callers that hold the lock when reaching a terminal seam. No re-entrancy risk introduced.
• Zero-value &Manager{} semantics preserved: nil terminal falls back to tmux, same as nil func fields did; funcTerminal's per-method nil fallback preserves the old unset-seam behavior for tests.
• Grepped the package for the eight removed field names: no stale references remain outside this diff (the one hit, paneCaptureSleep in manager_test.go, is an unrelated constant). Test rewrites are mechanical field-for-field swaps to termSeams(m).

[kubestellar-prow]

[APPROVALNOTIFIER] This PR is APPROVED

Approval requirements bypassed by manually added approval.

This pull-request has been approved by:

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[github-actions]

Thank you for your contribution! Your PR has been merged.

Check out what's new:

• KubeStellar Console — Live multi-cluster dashboard
• Marketplace — Community extensions
• Knowledge Base — Troubleshooting and how-tos

Stay connected: Slack #kubestellar-dev | Multi-Cluster Survey