feat: ttyd proxy, LAN auth, pop-out fix + multi-agent cleanup

[NetDevAutomate]

Summary

• Restore ttyd integration — 11 commits lost from reflog, cherry-picked and extended
• Same-origin reverse proxy — ttyd HTTP + WebSocket proxied through FastAPI at /terminal/, fixing iframe WebSocket drops on pop-out/return
• LAN password protection — HTTP Basic Auth middleware with timing-safe comparison. Password via --password flag, lan_password config, or auto-generated
• Pop-out persistence — iframe stays in DOM (CSS visibility), pop-out auto-closes on return to inline
• Multi-agent cleanup — Kiro crash recovery, MCP path fixes, OpenCode frontmatter update, schema drift fix

Test plan

• 589 tests passed, 6 skipped (pre-existing optional dep skips)
• 12 proxy tests — HTTP forwarding, HTML paths, app interface, X-Frame-Options
• 22 auth tests — no-auth passthrough, 401 enforcement, wrong/correct password, auto-gen, settings
• 2 WebSocket relay tests — keystrokes reach tmux through proxy, output flows back
• 5 Playwright UI tests — panel visibility, collapse toggle, popout button, iframe src path
• All pre-commit hooks pass (ruff, pyright, detect-secrets)
• Manual verification: pop-out → close → "+" returns terminal inline

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR restores and extends the web terminal (ttyd) integration by proxying ttyd HTTP/WebSocket traffic through the FastAPI web app at /terminal/, adds LAN-mode HTTP Basic Auth, improves the session dashboard terminal UI (split pane + pop-out persistence), and includes several multi-agent cleanup fixes.

Changes:

• Add same-origin /terminal/ reverse proxy (HTTP + WebSocket) and embed it in the session dashboard with split-pane + pop-out behavior.
• Add --lan and --password flows for the web dashboard (Basic Auth) plus new settings for web/ttyd ports and browser auto-open.
• Add new tests for proxy/auth/UI behaviors, plus agent launcher fixes (Kiro recovery, MCP command selection, OpenCode schema/frontmatter updates).

Reviewed changes

Copilot reviewed 28 out of 30 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
uv.lock	Adds deps for terminal proxy + Playwright-based E2E testing.
scripts/record-demo.py	New Playwright script to record a demo session video.
README.md	Documents --web, --lan, LAN password, and ttyd installation.
packages/studyctl/tests/test_web_terminal.py	Adds Playwright E2E coverage for terminal panel UI + (optional) ttyd integration.
packages/studyctl/tests/test_web_app.py	Updates X-Frame-Options expectation to SAMEORIGIN for iframe embedding.
packages/studyctl/tests/test_terminal_proxy.py	Adds HTTP proxy + HTML path/interface tests for /terminal/ proxy and app factory args.
packages/studyctl/tests/test_session_db_integration.py	Updates migration tests to assert current schema version constant.
packages/studyctl/tests/test_orchestrator.py	Adds unit tests for start_ttyd_background() behavior.
packages/studyctl/tests/test_lan_auth.py	Adds tests for Basic Auth LAN protection and settings parsing.
packages/studyctl/tests/test_agent_launcher.py	Adds tests for Kiro crash recovery and MCP command/schema updates.
packages/studyctl/src/studyctl/web/static/style.css	Adds split-pane and terminal panel styling.
packages/studyctl/src/studyctl/web/static/session.html	Adds split layout + embedded terminal panel + pop-out persistence UI/logic.
packages/studyctl/src/studyctl/web/routes/terminal_proxy.py	New same-origin reverse proxy for ttyd (HTTP + WebSocket relay).
packages/studyctl/src/studyctl/web/auth.py	New Basic Auth middleware for LAN protection.
packages/studyctl/src/studyctl/web/app.py	Adds ttyd port/password to app factory, registers terminal proxy, updates headers.
packages/studyctl/src/studyctl/settings.py	Adds ttyd_port, web_port, browser, lan_password config fields.
packages/studyctl/src/studyctl/session/orchestrator.py	Adds Claude trust bypass, tmux window sizing, web auto-open, ttyd background start.
packages/studyctl/src/studyctl/session/cleanup.py	Ensures background PIDs (web/ttyd) are terminated on session end.
packages/studyctl/src/studyctl/parking.py	Ensures migrations always run; adds drift-recovery fallback creation.
packages/studyctl/src/studyctl/doctor/deps.py	Adds doctor check for optional ttyd system binary.
packages/studyctl/src/studyctl/cli/_web.py	Adds --password and --ttyd-port, LAN password generation, passes config into app factory.
packages/studyctl/src/studyctl/cli/_study.py	Adds --lan/--password, starts web + ttyd, persists LAN info to session state.
packages/studyctl/src/studyctl/cli/_doctor.py	Registers new system binary checks.
packages/studyctl/src/studyctl/agent_launcher.py	Adds Kiro stale-backup recovery; shared MCP command builder; OpenCode frontmatter/schema updates.
packages/studyctl/pyproject.toml	Updates web extra deps, adds e2e marker, adds dev dependency group.
docs/system-overview.md	Updates diagrams/sequence to include ttyd + /terminal/ proxy + LAN auth.
docs/setup-guide.md	Adds remote study (--lan) guidance + web/terminal config docs.
docs/roadmap.md	Marks ttyd/LAN/proxy work as completed.
docs/cli-reference.md	Documents new CLI flags and terminal panel behavior/config.
.gitignore	Ignores new local docs paths and demos/.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The LAN Basic Auth middleware is implemented as BaseHTTPMiddleware, which only runs for HTTP scopes; WebSocket connections to /terminal/ws will bypass auth and allow unauthenticated terminal access when --lan is used. Add WebSocket auth enforcement (e.g., an ASGI middleware handling both http/websocket scopes, or explicit Authorization checking before ws.accept()), and add a test covering the WS handshake under auth.

[Copilot]

The WebSocket proxy builds the upstream query string via string concatenation without URL-encoding. If ttyd query params contain special characters, this can produce an invalid upstream URL. Use urllib.parse.urlencode (or httpx.QueryParams) to construct the query string safely.

[Copilot]

_open_browser() calls os.fork() unconditionally. This will raise on Windows (no fork) and can break studyctl study --web/--lan entirely. Please guard with hasattr(os, 'fork') / platform checks and fall back to a cross-platform approach (e.g., subprocess.Popen of a detached helper, multiprocessing.Process, or just best-effort webbrowser.open without fork on Windows).

Suggested change

	def _open_browser(url: str) -> None:
	"""Open URL in the configured browser after polling for server readiness.
	Uses os.fork() to create a child process that survives the parent's
	os.execvp(tmux attach). Daemon threads don't survive exec, but forked
	children do (reparented to PID 1).
	"""
	pid = os.fork()
	if pid != 0:
	return # Parent continues with session startup
	# Child process — poll then open browser
	try:
	import time
	import urllib.request
	import webbrowser
	# Poll until server is ready (up to 10 seconds)
	for _ in range(20):
	try:
	urllib.request.urlopen(url, timeout=1)
	break
	except Exception:
	time.sleep(0.5)
	else:
	os._exit(0) # Server never started
	browser_name = ""
	try:
	from studyctl.settings import load_settings
	browser_name = getattr(load_settings(), "browser", "")
	except Exception:
	pass
	browser_map = {
	"chrome": "Google Chrome",
	"safari": "Safari",
	"firefox": "Firefox",
	"brave": "Brave Browser",
	}
	if browser_name and browser_name.lower() in browser_map:
	app = browser_map[browser_name.lower()]
	# macOS: use open -a for specific browser
	subprocess.Popen(
	["open", "-a", app, url],
	stdout=subprocess.DEVNULL,
	stderr=subprocess.DEVNULL,
	)
	else:
	webbrowser.open(url)
	def _poll_and_open_browser(url: str) -> None:
	"""Poll for server readiness, then open the URL in a browser."""
	import time
	import urllib.request
	import webbrowser
	# Poll until server is ready (up to 10 seconds)
	for _ in range(20):
	try:
	urllib.request.urlopen(url, timeout=1)
	break
	except Exception:
	time.sleep(0.5)
	else:
	return # Server never started
	browser_name = ""
	try:
	from studyctl.settings import load_settings
	browser_name = getattr(load_settings(), "browser", "")
	except Exception:
	pass
	browser_map = {
	"chrome": "Google Chrome",
	"safari": "Safari",
	"firefox": "Firefox",
	"brave": "Brave Browser",
	}
	if browser_name and browser_name.lower() in browser_map:
	app = browser_map[browser_name.lower()]
	# macOS: use open -a for specific browser
	subprocess.Popen(
	["open", "-a", app, url],
	stdout=subprocess.DEVNULL,
	stderr=subprocess.DEVNULL,
	)
	else:
	webbrowser.open(url)
	def _open_browser(url: str) -> None:
	"""Open URL in the configured browser after polling for server readiness.
	On platforms with os.fork(), use a child process so browser opening
	survives the parent's os.execvp(tmux attach). On platforms without
	fork support (for example Windows), fall back to a best-effort direct
	call rather than raising.
	"""
	if not hasattr(os, "fork"):
	try:
	_poll_and_open_browser(url)
	except Exception:
	pass
	return
	pid = os.fork()
	if pid != 0:
	return # Parent continues with session startup
	# Child process — poll then open browser
	try:
	_poll_and_open_browser(url)

[Copilot]

_ensure_claude_trust() silently modifies ~/.claude/settings.json to bypass Claude Code’s trust prompt. This is a surprising side effect with security implications (it effectively auto-trusts a directory without explicit user consent). Consider making this opt-in (CLI flag/config/env), and/or at minimum print a clear message the first time it writes and restrict it to only the exact session directory rather than the parent.

[Copilot]

swap-panels sets an inline flexDirection based on the current layout, but toggle-layout doesn’t update that inline style when swapped is already true. This can leave the panel order wrong after toggling between stacked/side-by-side while swapped. Update the toggle-layout handler to re-apply the correct flexDirection when swapped is true (or compute direction from state instead of mutating style imperatively).

[Copilot]

start_ttyd_background() is started unconditionally, even when the user didn’t request --web/--lan. That spawns an extra background process and exposes a local HTTP terminal unnecessarily. Consider starting ttyd only when the web dashboard (or a dedicated --terminal/config flag) is enabled.

[Copilot]

The “auto-generated password” tests here only assert properties of secrets.token_urlsafe(16) itself; they don’t exercise the actual code paths that generate/print/store the LAN password (in studyctl web or studyctl study --lan). These tests would still pass even if the application stopped generating sufficiently long passwords. Consider refactoring password generation into a helper that can be unit-tested, or integration-testing the CLI behavior/output/state update.

Suggested change

	# Auto-generated password strength
	# ---------------------------------------------------------------------------
	class TestAutoGeneratedPassword:
	"""The auto-generated password must be sufficiently strong."""
	def test_generated_password_is_16_or_more_chars(self) -> None:
	import secrets
	pwd = secrets.token_urlsafe(16)
	assert len(pwd) >= 16
	def test_generated_password_is_unique(self) -> None:
	import secrets
	pwd1 = secrets.token_urlsafe(16)
	pwd2 = secrets.token_urlsafe(16)
	assert pwd1 != pwd2
	# Settings-backed LAN password integration
	# ---------------------------------------------------------------------------
	class TestLanPasswordIntegration:
	"""A LAN password loaded from settings must be enforced by the app."""
	def test_loaded_lan_password_requires_auth(self, tmp_path) -> None:
	"""A stored lan_password should make unauthenticated requests fail."""
	from studyctl.settings import load_settings
	config = tmp_path / "config.yaml"
	config.write_text("lan_password: mylanpass\n")
	with pytest.MonkeyPatch().context() as mp:
	mp.setenv("STUDYCTL_CONFIG", str(config))
	import studyctl.settings as settings_mod
	original = settings_mod._CONFIG_PATH
	settings_mod._CONFIG_PATH = config
	try:
	s = load_settings()
	app = create_app(password=s.lan_password)
	client = TestClient(app)
	resp = client.get("/")
	assert resp.status_code == 401
	finally:
	settings_mod._CONFIG_PATH = original
	def test_loaded_lan_password_allows_authenticated_access(self, tmp_path) -> None:
	"""The password loaded from settings should successfully authenticate."""
	from studyctl.settings import load_settings
	config = tmp_path / "config.yaml"
	config.write_text("lan_password: mylanpass\n")
	with pytest.MonkeyPatch().context() as mp:
	mp.setenv("STUDYCTL_CONFIG", str(config))
	import studyctl.settings as settings_mod
	original = settings_mod._CONFIG_PATH
	settings_mod._CONFIG_PATH = config
	try:
	s = load_settings()
	app = create_app(password=s.lan_password)
	client = TestClient(app)
	resp = client.get("/", headers=_basic_auth_header("user", s.lan_password))
	assert resp.status_code == 200
	finally:
	settings_mod._CONFIG_PATH = original

[Copilot]

This test module’s docstring and comments claim a WebSocket relay test for /terminal/ws, but no such test is implemented in the file. Either add a WS relay test (and auth coverage if applicable) or update the docstring so it matches the actual coverage.