Login shell contract, launch practice and landscape refresh (2026-09-29) - #498

Scope

• What this PR changes, in one or two sentences: decides the open items of the terminal decision by research convergence and records the evidence. A scrub-mode claude -p probe of a peer session left an empty ~/.bash_profile that hid ~/.profile, so every new Windows Terminal tab printed exec: claude: not found (exit 127); this adds the decision-record update (cause, evidence, decisions with rejected alternatives and overturn conditions, landscape refresh), a supersession pointer on the earlier agent-view paragraph, one recipe bullet, three anti-pattern rows (this incident's and the two of the earlier update, which that change left out so its pull request could merge cleanly), the receipt and its scripts. The host changes it describes (the removed empty file, a real ~/.bash_profile that hands off to ~/.profile, and the practice repository's login-shell-path doctor check) are on the host and are not in this diff.
• Base commit: cf2960a7 (origin/main at the last rebase)
• Lane: lane:foundation
• Owned paths touched: docs/decisions/2026-09-28-terminal-experience.md, recipes/claude-native-profile.md, docs/harness-defaults.md, evidence/receipts/, evidence/artifacts/login-shell-contract-20260929/, and manifests/evidence.json (hot-file protocol: main's copy taken after each rebase, own receipt entry and files re-registered, last commit).
• Authorship: written by a Claude Sonnet 5.5 coordinator session, hence the commit trailer. Reviewed once by Codex GPT-6 (read-only, max) and a headless Opus (max); see Review.

SOTA sources

• Bash startup order and the hand-off idiom: GNU Bash Reference Manual, "Bash Startup Files" (maintainer's copy) and bash(1) 5.2.21 INVOCATION (a login shell reads only the first of ~/.bash_profile, ~/.bash_login, ~/.profile); the Arch (dot.bash_profile) and Fedora (dot-bash_profile) bash package skeletons, which ship a ~/.bash_profile that hands off to another startup file; Ubuntu 24.04 /etc/skel/.profile (not read when ~/.bash_profile or ~/.bash_login exists).
• anthropics/claude-code: issues #76236 (this exact empty ~/.bash_profile; closed not_planned by the stale bot 2026-09-01), #78072 (open, reproduced; maintainer comment 2026-08-17: persistent placeholders are intended, cleanup at exit is being considered), and, related and open, #94008, #81602 and #83497, all read only (nothing filed or commented); CHANGELOG.md 2.1.78, 2.1.247, 2.1.257 (/doctor warning for stale sandbox mask files) and 2.1.271; docs read 2026-09-29: env-vars (the CLAUDE_CODE_SUBPROCESS_ENV_SCRUB row does not mention the placeholders), sandboxing (troubleshooting: 0-byte read-only placeholders removed after each command), errors ("Stale sandbox mask files left by a killed session"), agent-view, cross-session-messaging, cli-reference; the installed 2.1.284 binary (sandbox startup: fixed list of paths opened in append mode, and /tmp/inline-comments-buffer.jsonl).
• openai/codex at rust-v0.157.1 (installed) and rust-v0.158.0 (newest stable, 2026-09-28): codex-rs/tui/src/chatwidget/notifications.rs, codex-rs/tui/src/notifications/mod.rs, codex-rs/tui/src/terminal_palette.rs (identical between the tags) and the Notifications, terminal_title, notification_method, notification_condition definitions in codex-rs/config/src/types.rs (identical).
• microsoft/terminal releases and doc/cascadia/profiles.schema.json BellStyle enum at v1.24.11911.0, v1.25.1912.0 and main (the two toast signals of the decision record are unchanged); wsl.exe --help (WSL 2.7.13.0: --exec, --cd, --shell-type).
• Candidate notifiers and multiplexers: every pin recorded in the decision is unchanged (repository heads equal the pins; none archived).
• No code was written where a maintained upstream exists: the hand-off is the distro convention, no upstream reproduction or cleanup tool was published, and the scripts under evidence/artifacts/ are measurement tools for this record's claims, not product code.

Evidence-class table

Local commands run

$ python3 scripts/validate.py
exit 0: {"components": 69, "hashed_files": 8070, "profiles": 4, "receipts": 170, "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 evidence/artifacts/login-shell-contract-20260929/login_shell_check_controls.py --real-host
five cases as expected; real host: pass
$ python3 -B evidence/artifacts/login-shell-contract-20260929/scrub_placeholder_probe.py
no variable: 0 empty files; variable, stock home: 27 empty files including ~/.bash_profile and ~/.local/bin gone from the login PATH; variable, real hand-off file: untouched, PATH kept; real home unchanged; shared temp file removed
$ python3 -B evidence/artifacts/login-shell-contract-20260929/landscape_refresh.py
toast signals false/false and diverged/diverged; Claude Code 2.1.284; Codex notification definitions identical
$ python3 checks/check-terminal-profiles.py ; python3 nativestack.py doctor        (host practice repository)
PASS 5 profiles; doctor login-shell-path PASS (its catalog-revision DRIFT is unchanged and unrelated)

The unit-test suite was not re-run for this change: it adds no code under a tested module (documentation, a receipt and measurement scripts), and the terminal decision's PR recorded the suite's identical 321 baseline failures on this host against clean main; CI's clean runner is the authority.

Decision record

docs/decisions/2026-09-28-terminal-experience.md: "Update 2026-09-29", with the decisions table (login shell, session names, resume, agent view, telemetry gaps), each with rejected alternatives and an overturn condition.

Review

Round 1: Codex GPT-6 (read-only, max: 6 findings) and a headless Opus (max: 12 findings) returned changes-needed; all were applied. The Opus review found a real error in a first draft (a "correction" of the cooperation recipe's claude agents --json sentence was wrong: the installed CLI lists interactive sessions, so the recipe stays untouched and the decision now records the measured output). The Codex review found that the probe left a shared /tmp file and misreported non-empty directories as empty. Repairs: the probe removes the client's shared temp file and per-directory state by name and checks the real home itself, counts empty directories properly and runs the native claude doctor; the changelog filter was widened (2.1.247, 2.1.257, 2.1.271); the Codex-launcher rationale, the doctor probe wording, the receipt provenance (login_path_digest.py, the bubblewrap version) and several overclaims were corrected.
Not run: the bounded re-check of that repair. The shared Claude weekly window read 0.72 (five-hour 0.24) and the shared Codex pool 93% when it was due, and a peer session asked for no non-critical Opus work; the max-effort Opus re-check was started, stopped after about 13 minutes and produced no output. In its place every repaired script was re-run and its output is in the receipt (probe, controls, landscape, digest, agents snapshot), and validate.py passes. A later reviewer may run the re-check.

Residuals (recorded, not fixed here)

• The reproduction stops at the API-key check: it shows the placeholders are created at startup, not what a full session or its exit does. Upstream says they persist and that cleanup at exit is being considered.
• The hand-off file protects the name ~/.bash_profile only; a creator that truncates or replaces an existing file is not covered, and the doctor has no scheduler.
• The Polaris distro's profiles, the agent view probe (not adopted), and the telemetry gaps (tab identity, per-skill/agent/MCP labels on metrics, project agent names shown as custom, traces, per-session dashboard, retention) are outside this change; the telemetry items wait for their owners' measurement window.
• The doctor code is in the host practice repository, which has no remote; this change carries a copy of the check function with its controls.

Host evidence

Not applicable: no file under evidence/hosts/ is added or changed.

Checklist

• New/changed GitHub Actions are pinned to a full commit SHA with a version comment (none added or changed).
• New/changed workflows declare top-level permissions: contents: read (none added or changed).
• No secrets are printed, logged or committed (gitleaks clean on the commit; the reproduction uses a non-credential dummy value); no new required secret was added.
• No new paid hosting, subscription or billing surface was introduced.
• Peer-owned untracked files and worktrees were preserved.

Not merged by the author unless the merge guard passes (gh pr merge --squash --match-head-commit).

🤖 Generated with Claude Code