Tell the host terminal which checkout is on screen so relative links open the right file

[kaminskypavel]

Contents: 🐛 Symptom · 🔍 Cause · ✅ Fix · 📸 Before / After · 🔁 State · ⚠️ Risk · 🔧 Technical overview · 🧪 Proof · 📝 Notes

🐛 Symptom

Nebula shows many projects in one window, but the terminal around it never knew which one you were looking at. Clicking a relative file link (for example docs/experiments/2026-09-29-provider-costs/index.html) searched the wrong folder — wherever nebula was launched — and the link broke into a fake website address.

🔍 Cause

Nebula never told the host terminal which checkout is on screen. Folder reports from the shell inside are swallowed by the built-in parser, so the host kept its launch folder and resolved every relative link against it. No test looked at the raw bytes the host receives, so nothing caught it.

✅ Fix

• Announce the visible folder. Each time you switch sessions, nebula tells the host terminal "this is the folder on screen" using a standard terminal code (OSC 7). Quitting hands the original folder back.
• Unchanged. Typing cd inside a shell is still not tracked, and sessions over SSH stay silent rather than present a remote path as a local one.

📸 Before / After

No screenshots: the change is an invisible terminal code, so the difference is where relative links resolve.

Before	After
Links resolve against the launch folder	Links resolve against the checkout on screen
Switching sessions leaves the host folder stale	The host folder follows every switch and is restored on quit

🔁 State

Switch session → host learns the new checkout folder → next switch updates it again → quit restores the launch folder. Before, the host kept the launch folder the whole time.

⚠️ Risk

Verdict: 🟢 Low risk — a few extra bytes to your own terminal, only when the folder actually changed; nothing in the daemon, protocol, or database moves.

	Level	Why
🔒 Security & production	Low	Output goes to the terminal you sit at, local sessions only
⚡ Performance	Low	One short write per UI tick, skipped when the folder is unchanged
🧩 Fit with the codebase	Low	Lives next to the existing terminal-mode writers and reuses the current checkout lookup

Rollback: git revert <merge>; nothing persisted needs cleanup.

🔧 Technical overview

• The line that mattered. report_working_directory in crates/nebula-tui/src/event_loop/host_terminal.rs — the UI loop already sent pointer and clipboard codes to the host but never the working folder; now it sends a percent-encoded OSC 7 for the attached checkout.
• Why it was missed. The end-to-end harness checks rendered screen text, never the raw bytes the host receives.
• Why not track cd inside shells. That would mean tapping the parser on every folder report; checkout-level tracking covers session switches, which is the reported gap.

🧪 Proof

• Regression test. host_working_directory_follows_project_switches_and_restores_on_exit in crates/nebula/tests/e2e_tui.rs — fails on upstream/main (no folder bytes after adding a project), passes here.
• Gate. cargo test -p nebula-tui --lib: 1225 passed; cargo check --workspace --all-targets clean. Full e2e_tui: the new test plus 8 others pass; nebula_open_from_inside_a_session_raises_the_file_tabs and tui_drag_past_the_pane_top_autoscrolls_and_copies_the_run fail identically on a clean upstream/main checkout, so both are pre-existing.
• Manual check. Ran the patched build, added two projects, and watched the host-observed folder follow each switch and return to the launch folder on quit.

📝 Notes

• Based on upstream/main; protocol version and database schema untouched.