feat(api-tox): v2.2.1 Phase 1.2.1 — UX polish (drag-in-and-it-works)

[dreamrec]

Summary

Drag-in UX polish that emerged from the live-debug session against the v2.2.0 reliability features. Three friction points were silently making the chat-pipe a worse-than-it-needs-to-be experience for new users AND devs. This PR fixes all three.

Verified live in TouchDesigner pre-merge: maintainer rebuilt the .tox + sent yo from a fresh tab; chat round-trip succeeded with zero env-var toggles or pulse rituals.

The three friction points

#	Before	After
1	TDPILOT_API_INSECURE=1 was a process env var — wiped on every TD restart, so users dropped back into 401-land after every reboot.	Authmode is a COMP param (Menu: open / token, default open). Persists in the .toe. Read per-request, no Reloadconfig needed to flip.
2	Pasting a new Apikey value required two follow-up pulses (Saveapikey, Reloadconfig). Users said "I set the key but the agent doesn't see it."	parexec listens to valuechange=1; Extension.OnApikeyValueChange delegates to the existing save+reload path. Zero pulses required.
3	After every .tox rebuild the chat panel's CSRF token rotated. Every open browser tab 401'd until the user knew to manually navigate to http://127.0.0.1:9987/ for a fresh one.	The 401 catch branch in the chat JS now renders a yellow "Reconnect (reload this tab)" banner with a real <button> that calls window.location.reload(). One-click recovery.

Files

Modified (5 .tox-baked + 1 doc):

• td_component/build_tdpilot_api_tox.py — adds Authhdr section + Authmode Menu param under the API page; _wire_parexec enables valuechange=1.
• td_component/tdpilot_api_web_callbacks.py — _insecure_mode reads Authmode COMP param first; env var becomes a fallback for back-compat.
• td_component/tdpilot_api_parexec.py — onValueChange routes only Apikey and Authmode to the extension (every other value change is a no-op).
• td_component/tdpilot_api_extension.py — new OnApikeyValueChange + OnAuthmodeValueChange methods. The Apikey handler has an empty-string short-circuit to prevent recursion through OnSaveApiKeyPulse's Apikey.val = "" wipe.
• td_component/tdpilot_api_chat.html — new appendReconnectBanner() JS helper; /send catch branches on the 401 substring to surface the reload-button instead of the generic error.
• CHANGELOG.md — Phase 1.2.1 section under Unreleased.

New (1 test file): tests/test_v221_authmode_and_autoreload.py — 17 tests across 5 classes.

Binary update (2): td_component/tdpilot_API.tox + .tox-api-source-hash.json (rebuilt by maintainer in TD; freshness gate green at hash <new>).

Tests

Class	#	What it pins
TestInsecureModeFromAuthmode	6	Authmode=open/token, whitespace+case normalization, unknown-value falls through to env var; COMP param overrides env var.
TestBackwardsCompatibility	2	Old .tox (no Authmode param) still works via env var; _comp() returning None doesn't raise.
TestAuthGateEndToEnd	3	Open mode lets tokenless /send through; Token mode blocks; Open mode still rejects cross-origin (origin allowlist preserved — no LAN-RCE regression).
TestParexecValueChangeRouting	5	Apikey/Authmode route correctly; other params no-op; missing-extension and raising-handler paths don't crash the cook thread.
TestApikeyEmptyShortCircuit	1	Verifies the empty-string guard prevents the recursion loop through OnSaveApiKeyPulse's post-save wipe.

Test plan

• uv run pytest tests/ --ignore=tests/agent_evals -q — 1838 passed (1821 prior + 17 new).
• uv run --extra dev ruff format --check src tests scripts td_component — clean.
• uv run --extra dev ruff check src tests scripts td_component — clean.
• uv run python scripts/check_versions.py — in sync at v2.1.5 (no bump; v2.2.0 cuts when Phase 1 is complete).
• uv run python scripts/check_tox_freshness.py — dpsk4 .tox fresh (not touched by this PR).
• uv run python scripts/check_tox_api_freshness.py — API .tox fresh post-rebuild.
• bash scripts/check_no_personal_paths.sh — clean.
• Live in TD: maintainer dragged in rebuilt .tox + sent yo from a fresh tab. Round-trip succeeded with no auth toggle (proving default Authmode=open works as designed).
• CI all-green on push.

Security model — explicit migration note

The default chat-pipe webserver auth posture changes from token-required to origin-allowlist-only. This is appropriate for TouchDesigner's typical usage pattern (single-user creative coding on a personal box) and addresses the real friction it was creating, but it is a defaults change worth flagging:

• Same-machine attackers (other processes on localhost): previously needed to know the rotating session token to drive the chat-pipe. Now can hit POST /send directly. The threat model assumes you trust other code running on your own machine — same assumption already implicit in TouchDesigner's parameter system.
• Cross-origin browser attacks (any tab in your browser running attacker JS): STILL BLOCKED by the v1.7.1 origin allowlist + v2.1.3 JSON-envelope/CORS-preflight hardening. Open mode bypasses only the token check — the cross-origin gate is untouched.
• LAN attackers (other machines on the same WiFi): webserverDAT defaults vary across TD builds. If your TD binds to 0.0.0.0 (LAN-reachable), Open mode means anyone on the LAN can drive your chat-pipe. The Authmode = token flip restores the v2.1.3 protection one click away. Users in shared studio / venue / coffee-shop networks should flip it; users on personal laptops are fine on Open.

This trade-off is documented in the COMP's Authhdr section + CHANGELOG. The tdpilot-dpsk4.tox MCP server (port 9985) auth is untouched by this PR.

Why this should ship now (before Phase 1.5 / 2.1)

This is the kind of "rough edge nobody catches until a real user tries the system end-to-end" friction. The live-debug session in this session's earlier context surfaced exactly the failure modes this PR addresses — they're real, they're cheap to fix, and waiting to ship them means every additional Phase 1.x rebuild compounds the same workflow papercut.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3ebc76845c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Gate open auth mode behind the same exec clamp

Authmode=open now makes _insecure_mode() return True by default, which removes the X-TDPilot-Token requirement on /send, but the runtime hardening in TDPilotAPIExt._build_runtime still clamps TD_MCP_EXEC_MODE only when the env var TDPILOT_API_INSECURE is set. In practice this commit introduces a no-token path while leaving full exec enabled, so any local process (and LAN clients if the webserver is exposed) can drive agent turns that can reach td_exec_python with full privileges. The 2.1.3 mitigation needs to key off effective auth mode, not just the legacy env var.

Useful? React with 👍 / 👎.