refactor: rename --clear-screen flags to symmetric --clear-on-attach/--clear-on-detach

[eminwux]

Summary

• Renames the asymmetric --clear-screen / --clear-screen-on-detach pair (introduced days ago in fix: stop clearing terminal on attach/detach by default, add opt-in clear flags #426) to the symmetric, lifecycle-explicit --clear-on-attach / --clear-on-detach. "screen" is dropped — at the attach/detach boundary there is nothing else to clear, so the pair now reads as an obvious matched set.
• Hard rename, no backward-compat aliases — confirmed fix: stop clearing terminal on attach/detach by default, add opt-in clear flags #426's commit 0a171ff is in no tagged release (git tag --contains 0a171ff is empty; it lands after v0.12.5), so AC feat(session): add tty device to status spec #4's hard-rename branch applies.
• All layers from the issue's table renamed consistently: CLI flags (on both sb attach and the sbsh client root), SB_ATTACH_* / SBSH_CLIENT_* env vars + viper keys, ClientSpec / pkg/attach.Options / api.AttachRequest struct fields, and the JSON wire tags (clearScreen→clearOnAttach, clearScreenOnDetach→clearOnDetach).

Scope notes (calls the reviewer can push back on)

• Beyond the issue's table: the table didn't enumerate the public builder surface, but it's the programmatic mirror of the flags and had to move for consistency: pkg/builder.WithClientClearScreen→WithClientClearOnAttach, WithClientClearScreenOnDetach→WithClientClearOnDetach (+ their internal clientConfig fields), and pkg/attach.Options.ClearScreen/ClearScreenOnDetach→ClearOnAttach/ClearOnDetach. pkg/spawn.buildClientAttachArgs (the producer of the sb attach argv) was updated in lockstep with the renamed flag strings. Leaving these on the old names would have re-created the exact asymmetry the issue removes. All are fix: stop clearing terminal on attach/detach by default, add opt-in clear flags #426-era, pre-entrenchment surfaces.
• Left as-is (issue explicitly permits): the internal lowercase clearScreen params/vars/struct fields in internal/terminal/terminalrunner/* and internal/client/clientrunner/terminal.go, plus the escClearScreen/escClearScreenHome consts (which literally name the \x1b[2J ANSI sequence, not the flag). Doc-comment / test-error references to the removed --clear-screen flag literal were updated to --clear-on-attach for accuracy.

AC #3 — on-disk metadata / migration (dev to confirm whether on-disk metadata is affected)

No migration path needed. Findings:

• The JSON tags clearScreen/clearScreenOnDetach live only on the ephemeral api.ClientSpec (pkg/api/client.go). The persistent server-side api.TerminalSpec carries no such field, so persisted terminal metadata is unaffected.
• The clear settings are supplied fresh from flags on every sb attach; the live session's behavior is driven by the in-memory Spec value (io.go, lifecycle.go), never read back from a persisted client doc to drive the clear. The on-disk client doc is written for live-client discovery only. A pre-rename client doc belongs to a still-running pre-rename client whose behavior is already in memory — so a hard tag rename cannot make an existing session "silently lose the setting." Clients are short-lived (one per interactive attach).

AC #6 — docs/README references

git grep over the whole tree for the old flag/env/viper literals on non-.go files returns none, so no documentation follow-up issue is warranted.

Test plan

• make sbsh-sb — canonical build; binary is ELF (7f 45 4c 46), sb/sbsh hardlinked.
• ./sb attach --help and ./sbsh --help show --clear-on-attach / --clear-on-detach; --clear-screen* no longer present.
• go build ./... clean.
• go vet ./... clean.
• make test (full CI target, incl. e2e) — all green.
• go test ./pkg/... — all green (builder/spawn/attach/api tests updated for the new names).
• Tree-wide git grep confirms no remaining --clear-screen / CLEAR_SCREEN / old viper-key / exported ClearScreen* identifiers (only the permitted internal lowercase locals + ANSI-escape consts remain).

Closes #430

[eminwux]

PR #432 Review — refactor: rename --clear-screen flags to symmetric --clear-on-attach/--clear-on-detach

LGTM — complete, symmetric hard-rename across every layer (CLI flags, env/viper keys, ClientSpec/Options/AttachRequest fields, JSON wire tags, and the pkg/builder public façade); tree-wide grep confirms zero dangling old identifiers, the old names shipped in no tagged release (0a171ff not in any tag) so dropping back-compat aliases is safe, and CI is green.