punkshell/goals/G-009-themed-subshell-profiles.md

G-009 Themed subshell profiles binding poshinfo schemes to behavioural configuration

Status: proposed Scope: src/modules/punk/repl-999999.0a1.0.tm, src/modules/poshinfo-999999.0a1.0.tm, src/modules/punk/console-999999.0a1.0.tm, src/modules/punk/island-999999.0a1.0.tm Goal: a subshell can be launched from a named profile binding a poshinfo-enumerated scheme to behavioural aspects (e.g. G-003 interp limits/hidden commands, punk::island filesystem access) so that restricted subshells are visually distinct, with the theme's terminal effects and associated profile data riding the G-008 state set. Acceptance: a named profile associating a poshinfo scheme with at least one restriction aspect (an interp limit, a hidden command, or island-restricted filesystem access) launches by name; the scheme's visual state applies on entry (at minimum prompt styling plus one underlying terminal aspect such as a palette change) and is removed/restored on quit via the G-008 mechanism; profile-associated non-terminal data is scoped to the subshell's lifetime; an unthemed launch is unchanged.

Context

Subshells with restricted capabilities (G-003 interp limits and hidden commands, punk::island filesystem restrictions) should be visually distinct so the user always knows which trust context they are typing into - a security-usability property, not decoration. The poshinfo module already enumerates schemes suitable as the visual vocabulary. Applying a scheme is not just prompt styling: schemes may change underlying terminal state (colour palette, default fg/bg), which must be cleanly removed when leaving the subshell - and a profile may carry associated non-terminal data (prompt configuration, scheme identity, aspect settings) that needs the same push/pop lifetime.

Approach

• Named profiles bind: a poshinfo scheme + behavioural aspects (any of: G-003 interp limits, hidden/exposed command sets, punk::island filesystem access) + associated data. Launch by profile name (e.g. subshell <profile> or a -profile flag).
• Terminal effects ride G-008: the scheme's terminal-state changes (palette etc.) are declared into the subshell's console-state set at launch, so entry applies them and quit/switch-away restores the prior state through the same mechanism as journaled ad-hoc mutations - no second restore path.
• Non-terminal profile data (scheme identity, prompt config, aspect parameters) is scoped to the subshell's lifetime alongside the state set.
• Fail-safe distinctness: if the terminal cannot honour the scheme's deeper effects (no palette support), the profile must still yield a visible distinction (prompt-level styling at minimum) - a restricted subshell must never silently look like an unrestricted one.

Alternatives considered

• Prompt-string theming only (no terminal-state effects) - insufficient as the design ceiling: easily missed, and scrollback regions written by the subshell carry no distinction; retained as the fail-safe minimum tier.
• Folding theming into G-003 - rejected: restriction mechanics and visual identity are orthogonal; G-003's acceptance is already substantial, and themes apply equally to unrestricted profiles.
• Ad-hoc theme application on entry with hand-written cleanup on exit - rejected: duplicates G-008's restore machinery and diverges from it exactly when switching (G-010) arrives.

Notes

• Depends on G-008 (state-set declaration/restore); applies aspects whose mechanisms are G-003's deliverables (limits, hide/expose) and punk::island's - this goal binds them into profiles, it does not re-implement them.
• Mapping a poshinfo scheme to concrete terminal state (which palette slots, fg/bg, prompt segments) is an implementation-time design task within poshinfo/punk::repl; the goal only requires that at least one underlying terminal aspect is driven by the scheme and correctly restored.