Appearance: real host config reads and reviewed, owned host overrides

docs/development/native-appearance-welcome-checkpoint.md

@@ -0,0 +1,5 @@
+# Native appearance / Welcome Studio continuity
+
+Research checkpoint only; no product implementation yet. Read [progress](native-appearance-welcome/progress.md), [handoff](native-appearance-welcome/HANDOFF.md), [decisions](native-appearance-welcome/DECISIONS.md), [verification](native-appearance-welcome/TEST_RESULTS.md) and [research](native-appearance-welcome/RESEARCH.md).
+
+Persistent local evidence: /Volumes/T7Tmp/ai-dev/nmsh-native-appearance-welcome-20261028. Tracked files are synchronized snapshots so another agent can reconstruct state without this chat. Inspect current Git HEAD/status to reconcile checkpoint provenance. Do not confuse this feature with stabilization PRs513/514. No merges/releases/production host-config writes/Homebrew actions.

docs/development/native-appearance-welcome/DECISIONS.md

@@ -0,0 +1,22 @@
+# Architecture findings and recommended direction
+
+The human explicitly approved this implementation direction and waived the design-document approval gate. Recommendations below guide implementation; meaningful trade-offs are recorded here.
+
+- Reuse PromptConfiguration and current canonical editors. AppearanceHub launches canonical editors, not copies. Extend cursor/native and existing host integration rather than create contradictory persistence.
+- First repair existing Ghostty appearance: readGhosttySettings returns fabricated constants, saveGhosttySettings silently appends an include and overwrites a fragment. These cannot be reused unchanged for the requested safety contract. Reuse inspected Theme Bridge ownership/verified-edit patterns where applicable; further audit required.
+- Host capability is separate from implemented NMSh presets and loaded-state evidence. Kitty's old backend exposes only tail; broadening it must accompany actual generator support and version/catalog checks, not capability advertising alone. Unknown versions fail closed for new features.
+- Kitty pipeline compiler and Ghostty GLSL compiler share logical settings only. Validate composition, parameters and dependencies, preserve pre-existing shaders/includes, disclose unresolved effective values rather than invent defaults. Native adoption is explicit; native and Portable overlap must be suppressed, including pending reload state.
+- Audit loaded-vs-written integration state. A written fragment does not prove a renderer loaded it. Switching Portable/reduced-motion cannot be claimed effective while old host shader remains loaded. Manual reload/restart status must remain visible and ambiguous overlap must not be painted twice. Further design needed for safely managing surface-wide native lifetime across fullscreen handover without per-event reload.
+- NMSh already has a semantic Transition union, per-event look/timing, cancellation, deterministic paints and PresentationClock. Extend these, not an independent scheduler/event engine. Clean/Rich controls and Chroma palette remain canonical. Terminal-wide shader events are not NMSh widget events. Do not use BEL as a command-success channel (audible/unrelated side effects), magic pixel markers, remote arbitrary-window updates or per-event config rewrites.
+- Use existing GraphicsService and ImageSurface typed builders/owner cleanup for welcome. External capture remains SGR-only; never forward captured APC/OSC/DCS/raw output. Current GIF is first-frame-only; animation requires bounded actual frame decode/composition, disposal/timing and native upload/control extensions. APNG support likewise is work, not a flag.
+- Full-terminal P preview and startup share one welcome composition and sequencing service. Preview lifecycle acquires alternate screen/input, releases owned graphics on every exit and restores draft/selection. No session recreation or startup shell execution. Static final snapshot belongs to transcript; animation frames/bytes do not.
+- Read Fastfetch JSONC as bounded data; never execute Neofetch shell config to discover logos. Only literal recognized assignments can be imported. Dynamic sources/includes require truthful unsupported guidance. Existing provider execution contract is distinct from safe new static system-info fields.
+- New fields may use only explicit typed facts/static text, no automatic shell commands. Sensitive hostname/path/Git facts opt-in; presets omit private asset bytes/paths unless explicitly exported. Original assets are immutable.
+- Proposed implementation bounds (builder decisions, not agreed): <=8MiB welcome asset input, <=2MP source, <=320x240 animation canvas, <=75frames, <=15fps, <=5seconds per startup playback, <=32MiB decoded animation data, bounded cache within existing GraphicsService budget. Validate both frame count and total bytes before allocating; unsupported/over-budget assets get deterministic still fallback or actionable refusal. Existing general viewer limits remain unchanged. No AI segmentation claims or new dependency without justified need.
+- Independent PR slices required. Do not combine whole program into one feature PR. All required features remain in scope; unsupported native semantic targeting has production Portable fallback as explicitly requested.
+
+Ruling: Ghostty version-tagged source loads legacy config before preferred config.ghostty, then all recursive includes via a global appended queue after every default root; documentation overview is ambiguous. Implement source order and simulate proposed fragments, refusing a later nested-include conflict. Treat unresolved theme-derived fields as unknown rather than defaults. Dynamic includes and external/symlinked config roots are conservatively blocked in this slice.
+
+Ruling: preserve the existing Theme Bridge ledger design concept but isolate host ownership records; Theme Bridge targets and current write primitives do not provide this transaction/dependency contract. Use exclusive staging, captured file identity/content, checks before staging and immediately before rename, and rollback of only unchanged task writes. POSIX rename is not atomic compare-and-swap; do not claim protection against arbitrary concurrent malicious directory swaps. Group/world-writable paths are refused.
+
+Ruling: preserve valid unchanged numeric blur above the normal UI range during unrelated saves. Require nonnegative safe integers in generated data; UI normally caps increases at50 but can decrease a larger existing value incrementally. Display bars clamp without changing stored values.

docs/development/native-appearance-welcome/HANDOFF.md

@@ -0,0 +1,49 @@
+# Native appearance and Welcome Studio handoff
+
+## Objective and required scope
+
+Implement native GPU Shader Studio and host appearance, plus a comprehensive Welcome Studio under /appearance. /cursor and /welcome must open canonical editors. Preserve persistent zsh/Bash/Fish PTY, input ownership, raw output, copy, viewport and existing settings. No duplicate engines or contradictory Clean/Rich, Chroma, cursor or welcome settings.
+
+Shaders: Auto/Host Native/Portable per host; decorative effects opt-in; initial exact config diff and consent; ownership ledger, safe atomic writes, conflict disclosure, rollback/removal. Kitty >=0.49 Slang/pipelines with installed official catalog, bounded variables, composition/event/texture validation. Ghostty GLSL is separate. Extend opacity/blur/background, fix false reads/discovery, truthful capabilities/reload/restart. No remote-control permissions or automatic source download/execution. Do not overwrite user config/themes/keybindings/shaders.
+
+Welcome: preserve Vespyr/Fastfetch/installed-only Neofetch/Macchina/Zigfetch/None, add customizable native layout. Existing external configuration and logos read-only. Local path entry (absolute, relative, ~/), local navigable image-filtered picker, metadata, contain/cover/crop/alpha, PNG/JPEG/WebP/GIF/APNG and safe ANSI/ASCII. Validate assets, bounded animation decode/composition and cache, preserve originals. Still-image effects: float, pulse, layered parallax, glow, shimmer, particles, reveal, pan/zoom, original. No fabricated character motion, cloud uploads or implicit generators. Rich layout/palette/title/borders/mascot/text/links/greeting/module customization and preset save/duplicate/import/export/reset. Sensitive facts opt-in; no arbitrary shell fields. Do not export private source images/paths silently.
+
+Both live editor preview (pause/replay, compact/expanded, narrow/wide, theme/reduced-motion, imported before/after) and P actual full-terminal alternate-screen preview are REQUIRED. Preview and actual startup share composition/layout/renderer/animation sequencing. Real host images and animations where supported; production fallback explained otherwise. Esc restores unsaved draft/selection. No OS resize/fullscreen, duplicate shell/session/startup commands, transcript frames or input leakage. Startup must not block shell readiness. Stop on input/leave/resize/detach/shutdown/handover and release graphics/timers. Keep saved-session semantics and one provider capture.
+
+All visual systems need investigation and justified integration: prompt, Chroma, Clean/Rich, expressions, command lifecycle, queue/approval, notifications, welcome, idle. Extend common semantic animation model (event/target/timeline/look/colors/intensity/speed/cancel/capability/preference). Existing text/layout/renderers remain authoritative. Use native only with reliable documented targeting/events, otherwise existing Portable. Never fake targeting through pixels or config writes/reloads per event. No overlapping native/Portable effects. Reduced Motion, Effects Off, NO_COLOR win. Clean stays foreground-only/transparency-safe; Rich keeps intentional fills. No shader impacts on unrelated apps/windows.
+
+## Exact state
+
+Read progress.md and CHECKPOINT.json, then reconcile with Git. The explicit human design-gate waiver is granted. Slice1 product changes are uncommitted on pushed research HEAD a7bbfb33f515ad5c7f0359a3f7baa0eb92b2a13c. Baseline source c690de055daeb7b33ed8b5e302ef01133b3e55b4 is unchanged remotely. No feature PR yet. Do not discard the dirty files: they contain the safe host appearance implementation and tests. Dependencies installed in this isolated worktree.
+
+Evidence: /Volumes/T7Tmp/ai-dev/nmsh-native-appearance-welcome-20261028. Tracked synchronized snapshots: docs/development/native-appearance-welcome/. The JSON receipt is the current local event record; tracked documents travel with Git. Preserve raw logs and source manifest.
+
+Primary checkout remains separate and must not be switched/reset. Preserve shared stashes and active sessions. #513 head a57568be5e8b11cf927a00371c1b4783cadde53d and draft #514 head416bc51a4f6151236d959ef6a62d2d1653772287 remain unrelated/open/unmerged with failed comprehensive gates. No stabilization source was imported.
+
+## Environment
+
+Sandbox diskutil cannot access DiskManagement; sandbox t7run fails identity. Elevated t7run --check PASSED and verified physical T7 UUID73CBDC38-3B3A-32A4-B18C-C06D627FB10F, APFS UUID62D4E8A9-087C-4927-A62F-25BB88B7F1C7, backing /Volumes/T7 Shield/nmsh-tmp.sparsebundle. Use real elevated preflight, never bypass guard or fall back internally. Scratch free approximately6.1GiB at checkpoint. Reads/network sometimes need elevation too. Launch scratch tools via t7run; NMSH_TEST_TMPDIR=/Volumes/T7Tmp/ai-dev for short test socket paths. Read full AGENTS, ~/.codex/RTK.md and ~/.config/ai-storage/policy.md. Prefix shell commands with rtk.
+
+Installed Kitty reports0.49.2. Installed Ghostty remains1.3.1. User authorized updating hosts, then latest addendum prohibits further Homebrew work. Homebrew metadata/runtime were refreshed7.0.10->7.0.11; Ghostty1.4.0 download succeeded but upgrade failed at hdiutil attach Permission denied. No installed Ghostty app/config was replaced. Official DMG checksum3a02075dbd24318d778426af41dee5507d53ecc4578ede96912ec9ce6d18d3e8. diskutil image attach --readOnly worked. Signature-verified1.4.0 staged at /Volumes/T7Tmp/ai-dev/downloads/nmsh-ghostty-1.4.0-20261028/Ghostty.app; --version confirms1.4.0. Installer image disk17 was ejected successfully. No Ghostty GUI process/window launched. Staged app is preserved for validation, not a claim system Ghostty upgraded. Fastfetch reports2.68.1; animation support in this binary not yet established.
+
+## Next exact action
+
+**Claude continuation (2026-10-28):** newline-removal fix and Kitty `/keyboard` fix are in the working tree with regressions (see progress.md). Next: canonical verify on frozen source, independent review, commit/push Slice 1, then Slice 2 (Kitty native shaders). The Codex text below is historical.
+
+
+Finish stable Slice1 canonical verification; source/test contents are frozen and captured in slice1-source-manifest.json. Full first attempt overlapped edits and failed configuredCompletion.test.ts4096-record capture (actual0), so it is not baseline proof. Final focused32/32 and typecheck passed. Read logs and inspect every failure, without weakening tests or expanding into unrelated stabilization fixes. Complete independent re-review, preserve a coherent commit and focused draft PR targeting dev when safe; report physical QA pending. Never merge. Then continue PLAN.md Slice2 actual capability/catalog/native backends, not more design approval.
+
+Known limits of Slice1: static in-home non-symlink config graph only; unresolved themes/dynamic includes report unknown, not fabricated effective values. CLI overrides are not visible. Nested include conflicts can block setup intentionally. File identity is rechecked after staging, but POSIX pathname rename is not atomic compare-and-swap against arbitrary hostile races. No GPU support is claimed from this slice. Host installed/staged apps remain untouched.
+
+## Restrictions
+
+No merges, master edits, release/tag/deploy/Homebrew actions. No production host-config writes. Do not enable broad remote control. No automatic shader downloads or execution. Private HOME/config tests only. Physical Kitty/Ghostty/Zed QA is NOT RUN. No fabricated GPU, performance or terminal validation claims. Cleanup only task-owned disposable resources; keep worktree, original assets, stashes and unique evidence.
+
+## Claude Code — Resume from this checkpoint
+
+1. Run t7run --check in the actual environment (elevated if sandbox blocks DiskManagement); verify physical T7/APFS backing and GitHub connectivity. Stop disposable work if verification fails.
+2. Read AGENTS.md, RTK/storage policy and these checkpoint files, plus the referenced ownership report when local; tracked snapshots preserve portable continuation context.
+3. cd /Volumes/T7Tmp/ai-dev/worktrees/notMyShell/appearance-welcome-20261028; run git status --short --branch, git rev-parse HEAD, git remote -v, git log -5 --oneline and git ls-remote origin refs/heads/dev refs/heads/feature/appearance-welcome-20261028.
+4. Reconcile repository truth with progress.md/HANDOFF/TEST_RESULTS. Preserve all user edits/sessions/stashes and this existing branch. Do not create a duplicate feature branch or repeat completed functionality without evidence.
+5. The human explicitly approved implementation and waived the design gate; continue the next incomplete slice without repeating that gate. Independently review existing changes before integration. Do not merge.
+6. Update the SAME checkpoint files after every slice/meaningful validation and before costly tests/CI/compaction/end. Record exact HEAD, dirty state, committed/pushed changes, commands/results, PR/CI, decisions/risks and precise next task. Keep repository snapshots synchronized and push coherent checkpoints when safe.

docs/development/native-appearance-welcome/INDEPENDENT_REVIEW.md

@@ -0,0 +1,19 @@
+# Independent Slice1 source review
+
+Reviewer: separate fresh-context agent appearance_safety_review; read-only; no tests run by reviewer. Scope is the uncommitted safe host appearance slice on a7bbfb33, not the entire Shader/Welcome program.
+
+Initial important findings: Ghostty global include-queue precedence; unresolved theme defaults; staging window for concurrent edits; large blur display crash; host R intercepting Motion replay; valid named background rejected; raw background terminal-control injection. Additional notes: group-writable paths and residual pathname races.
+
+All findings were checked against code/source and pinned with failing behavioral regressions. Fixes: root+global queue order; simulated post-write effective configuration/refusal on shadowing; unknown theme-derived values; post-fsync expected snapshot check; group/world-writable refusal; clamped display and preserved high numeric blur; scoped host shortcuts; bounded named colors and control validation/sanitation. Tests include real concurrent file edit during staging and a controlled ledger rename failure restoring host+fragment.
+
+Final review: no material unresolved blocker in Slice1; high-blur issue resolved. Confirm/apply/removal separated, config reread after success, restore accessible when current values unresolved. POSIX check-to-rename interval remains a documented limit. No claim of arbitrary adversarial race immunity. Canonical verification and physical QA remained pending at review time.
+
+Review content is tied to slice1-source-manifest.json. Before commit, compare current source to that manifest. No product source changes after the final review request.
+
+## Claude continuation review (2026-10-28, separate read-only Sonnet reviewer, source manifest e894b2b5)
+
+No blocker. Both new fixes verified correct by reading (`withoutHook` LF/CRLF/empty/created-file cases; optional Ghostty-only `installKeyboard`).
+- should-fix 1: crash recovery. Writes go fragment → host hook → ledger. A crash during REMOVAL after the hook is gone but before fragment/ledger deletion leaves a ledger whose hook is absent; `planHostRemoval` then refuses forever ("owned include missing"). Other crash points block setup with clear messages but lose no user bytes. Planned fix: removal accepts "hook absent + ledger + owned fragment" and deletes only fragment and ledger (host file untouched), with a regression.
+- should-fix 2 (plausible): Kitty on macOS also reads `~/Library/Preferences/kitty/kitty.conf`; Kitty uses the FIRST existing config directory, unlike Ghostty's all-roots load. Verify against installed Kitty 0.49.2 (`kitty.constants.config_dir` logic) before changing hostPaths/readHostConfiguration.
+- minor: removal preview omits a restored line break; hub guidance not re-rendered after async read when hub closed; tiny window after apply where hub shows pre-write values; rename drops hardlinks/xattrs; stale XDG path blocks removal (fails closed). Recorded, not fixed in Slice 1.
+- Resolution: should-fix 1 FIXED (removal with the hook already absent deletes only the hash-verified fragment and ledger; the host file is a dependency, not changed). should-fix 2 CONFIRMED by probing installed Kitty (kitty-config-dir-evidence.md) and FIXED (worse than reported: Kitty would have loaded a new hook-only XDG file instead of the user's Preferences config). Minor items remain documented.