Terminal defaults in the repository: Claude overlay, Codex [tui] list, profile example, --login-shell; repairs of the #498 re-check - #510

Scope

• What this PR changes, in one or two sentences: carries the terminal defaults of the 2026-09-28/29 decision in the repository, so a new session or host takes them from the templates and docs instead of a host edit (a Linux/WSL2 Claude Code settings overlay, a Codex [tui] notifications list, a Windows Terminal profile fragment example, a static scripts/adoption_status.py --login-shell check, and a platform-page section), and repairs six defects that a bounded Opus re-check found in the already merged login-shell change (Login shell contract, launch practice and landscape refresh (2026-09-29) #498).
• Base commit: be97e882 (origin/main at the last rebase)
• Lane: lane:foundation
• Owned paths touched: adoption/platforms/linux-wsl2.md, adoption/templates/, examples/claude-native/, recipes/claude-native-profile.md, scripts/adoption_status.py, tests/, docs/decisions/2026-09-28-terminal-experience.md, docs/harness-defaults.md (two anti-pattern rows), evidence/receipts/, evidence/artifacts/login-shell-contract-20260929/, evidence/artifacts/wsl-terminal-defaults-20260929/, and manifests/evidence.json (hot-file protocol: main's copy, the two receipt entries and the hashes of the changed files).
• Authorship: written by a Claude Sonnet 5.5 coordinator session, hence the commit trailer. Reviewed by headless Opus reviewers at effort max (two lenses in round 1, two in a round-2 re-check of the repair); the Codex GPT-6 round could not run; see Review.
• Release note: the new and changed adoption files are not in the pinned release, so a new host gets them only after a release carries them and the manifest is re-pinned (scripts/release_due.py already lists earlier unreleased paths). The platform page says so in its own words ("added after v2026.09.26.2").

SOTA sources

• Bash login startup order: GNU bash 5.3 (bash-5.3.tar.gz, ftp.gnu.org) shell.c execute_profile_file L1116-1127 and builtins/evalfile.c maybe_execute_file / evalfile_internal (a missing file returns 0, an empty file, a directory and any other open error return nonzero, so the first file that exists ends the search); GNU Bash Reference Manual, "Bash Startup Files". The new static check is verified against the installed bash 5.2.21 itself (343 combinations), since bash offers no query API.
• Windows Terminal: JSON fragment extensions (folder %LOCALAPPDATA%\Microsoft\Windows Terminal\Fragments\{app-name}\, a profile guid is optional) and advanced profile settings (bellStyle, closeOnExit, suppressApplicationTitle), both fetched 2026-09-29; microsoft/terminal v1.24.11911.0 src/cascadia/TerminalSettingsModel/Profile.cpp L302-317 (_GenerateGuidForProfile) and CascadiaSettingsSerialization.cpp L1038-1041 (a fragment profile with no GUID gets a stable one from its name and source).
• Claude Code 2.1.284: settings reference (preferredNotifChannel notifications_disabled), hooks reference (terminalSequence, Notification types), environment variables (CLAUDE_CODE_TMPDIR, CLAUDE_CODE_SUBPROCESS_ENV_SCRUB), errors page (stale sandbox mask files), CHANGELOG entries 2.1.69, 2.1.83, 2.1.98, 2.1.141 and 2.1.257, and the installed binary's startup code (read by startup_placeholder_names.py).
• openai/codex rust-v0.157.1 (installed) and rust-v0.155.1 (the macOS pin): codex-rs/tui/src/chatwidget/notifications.rs type_name() for the notification kinds; the installed codex --strict-config for what a configuration accepts (measured).
• anthropics/claude-code issues #76236 and #78072, read only; nothing was filed or commented.
• No code was written where a maintained upstream tool exists: the overlay is applied by the repository's existing tools/adoption/apply_claude_settings.py, the profiles use Windows Terminal's documented fragment mechanism, and the --login-shell flag extends the existing scripts/adoption_status.py because no upstream equivalent exists.

Evidence-class table

Local commands run

$ python3 scripts/validate.py
exit 0: {"components": 69, "hashed_files": 8154, "profiles": 4, "receipts": 172, "status": "passed"}
$ python3 scripts/validate_foundation.py ; python3 scripts/component_matrix.py --check ; python3 scripts/new_host_grand_list.py --check
exit 0, 0 and 0
$ python3 -B -m unittest tests.test_adoption_status tests.test_windows_terminal_defaults tests.test_adoption_docs_consistency tests.test_render_config tests.test_apply_claude_settings   (Python 3.13.15 and /usr/bin/python3.12)
Ran 214 tests ... OK (skipped=1)
$ python3 -B evidence/artifacts/wsl-terminal-defaults-20260929/login_shell_bash_truth.py .
combinations checked: 512 | mismatches: 0 | negative control disagrees in 26 combinations (plus the FIFO and stat-error cases)
$ python3 -B evidence/artifacts/login-shell-contract-20260929/scrub_placeholder_probe.py
the real /tmp and /tmp/claude-<uid> gained 0 top-level entries; native doctor 3 warnings (sandbox off) and 4 (sandbox on, planted stale mask file named)

Decision record

docs/decisions/2026-09-28-terminal-experience.md: the new section "Repository-carried defaults and the second distro's profiles (2026-09-29)" (decisions with rejected alternatives and overturn conditions) and "Corrections after the bounded re-check (2026-09-29)".

Host evidence

This PR adds no file under evidence/hosts/.

• python3 scripts/host_receipts.py validate is part of scripts/validate.py, which passes.
• Independent review is recorded in this description (Review).
• No platform_status change is made from a host receipt alone.

Review

• Round 1 (headless Opus, effort max, read-only, a frozen checkout of the first head, two lenses): reviewer A (behaviour and tests against bash itself, receipt and evidence accuracy, publication hygiene, host-side state) returned 11 findings (4 medium, 7 low) and changes-needed; reviewer B (every upstream-behaviour claim against its primary source) returned 8 (3 medium, 5 low) and changes-needed. All were accepted and repaired. The ones that changed behaviour or evidence:
  • the repaired probe still wrote to the real /tmp when the caller's TMPDIR made its private path too long for the client's messaging socket (the client then falls back to a fixed /tmp/cc-socks-<uid> directory): the scratch path is now short and guarded, and a control probe shows both cases;
  • the overlay acceptance oracle could not see the Notification matcher (the merge de-duplicates hooks by command, so a catch-all group or an older matcher merges to itself): it now checks the group count and the matcher, a test proves it refuses both wrong hosts, and the platform page says a later matcher change needs the old group edited first;
  • the shared Codex [tui] notifications list also reaches macOS hosts: decided and documented (decision row, macOS page, bootstrap step 4);
  • --login-shell: an unusable ~/.profile is reported as not read, an unresolvable HOME is no longer a traceback, the special-file wording was wrong (a device reads as empty, a FIFO blocks), and ELOOP, ENOTDIR, EACCES, /dev/null and FIFO cases were added against real bash;
  • the doctor's silence about the scrub-created file follows from the warning's documented scope (0-byte read-only placeholders); the planted file only proves the warning is live.
• Round 2 (the one bounded re-check of that repair: two fresh headless Opus reviewers at effort max on the head after round 1, lenses split between behaviour and evidence and upstream sources): reviewer C returned 11 entries and reviewer D 8, both changes-needed, all low or medium, none high. All were verified against source and repaired; each repair carries its own check:
  • a claim of mine that an open Claude Code session "keeps the hooks it started with" was wrong (settings reference, "When edits take effect": hooks hot-reload); removed, and the real limit (no bell was observed) stays;
  • the socket-fallback condition is stated on the client's own 103-byte cap of <dir>/cc-socks/<pid>.sock (about 81 bytes of private path with a 7-digit pid; the control used 99), with XDG_RUNTIME_DIR left unset; the probes now report the shared file and refuse to interpret a run when a fallback directory already existed;
  • --login-shell falls back to / for HOME the way bash does; three mutants the review found alive (cwd instead of the passwd home, profile_read only for content, no root fallback) are now killed by tests, shown by rerunning each mutant;
  • the practice repository's check now derives the GUID of a fragment profile that declares none (the first fix let an override under that GUID pass unchecked: shown at exit 0 before, exit 1 now), with three mutant controls (22 in all) computed from Microsoft's recipe independently;
  • the second distro's binary is shown byte-identical to this host's 2.1.283 (SHA-256 prefix) with occurrence counts; request_user_input questions notify as plan-mode-prompt at both Codex tags (tool_requests.rs L449-458), so no notification the macOS pin emits is lost; a profile's environment replaces profiles.defaults.environment; the .env* working-directory placeholder list is named.
    There is no third round. Residuals are in the receipts' limitations: no Windows Terminal tab or bell was observed, nothing was run on a Mac, and the second distro's open sessions were not observed picking the overlay up.
• Codex GPT-6 cross-family round: not run. On 2026-09-29 at about 14:00Z the native Codex account answered "You've hit your usage limit ... try again at Oct 3rd, 2026 8:35 PM", and the OmniRoute pool answered 429 Too Many Requests with every one of its six weekly windows at 99-100%. That is a retained failure of the lane, not a skipped review; the user was notified. The round runs on the merged commit when a login or the reset restores the lane.

Checklist

• New/changed GitHub Actions are pinned to a full commit SHA with a version comment (no workflow is changed).
• New/changed workflows declare top-level permissions: contents: read (no workflow is changed).
• No secrets are printed, logged or committed; no new required secret was added. The added lines were scanned for user names, home paths, GUIDs, credential shapes and e-mail addresses: 0 hits.
• No new paid hosting, subscription or billing surface was introduced.
• Peer-owned untracked files and worktrees were preserved (not deleted, moved or overwritten).

🤖 Generated with Claude Code