feat(web): first-run welcome wizard with agent setup and project import

[t3dotgg]

Fresh installs need a clear path to connect the computer that has their code, set up agents, and bring existing work into T3 Code. Existing workspaces continue straight to the app.

This adds a full-screen first-run welcome flow with no logo chrome. Users can run on the local computer, connect through T3 Connect, or pair a server directly. Provider readiness detects only Codex and Claude Code by default.

The selected provider instance's binary, account home, and environment are used consistently for readiness, setup, and runtime. The server resolves terminal values before it starts the PTY, while Settings and terminal metadata stay redacted. Legacy Codex and Claude settings still resolve under their default instance IDs, and explicit instances take precedence. Terminal errors retain their server-settings cause for diagnostics without exposing it in the user-facing message. POSIX home paths expand correctly while spaces and shell operators stay quoted.

The import step finds recent Codex and Claude Code work. Discovery accepts only regular transcript files and shares a 20,000-operation budget across directory reads and candidate stats for each provider source. Successful imports keep their thread identities across partial import, retry, and reload. This prevents duplicate projects or conversations. Import order is a total order: malformed timestamps sort before valid timestamps, valid timestamps use absolute time, and malformed ties use code-unit order. The first prompt stays within the 200-message cap, and completion lands on a selected project that imported history. Completion retry also keeps the saved client appearance settings and selected project target. Imported conversations remain resumable and do not publish live Done alerts through the relay.

The first-run gate waits for settings and authoritative environment data. Slow startup stays pending and offers Reload instead of mounting the app. The gate keeps the onboarding theme through recovery and wizard routing, so a saved light or custom theme cannot flash between states. Completion waits for the settings write before it closes. Active custom themes are restored afterward. Server welcome state follows the current session under one lock, so buffered events cannot restore stale session data. The authentication confirmation cache also prevents false success without an extra GET request.

Scope: this PR covers first-run import through /welcome. Post-onboarding import, external-turn refresh, and safe single-writer handoff remain tracked in Discussion #6680. Merging this PR does not complete that request.

Browser evidence

Final head: 1c765685aa587a408b3b2c6386b943efef9d4ce0

Before: earlier pull request version	After: final head

Slow startup recovery

Watch the delayed-start recovery flow

Agent readiness

Project import

Saved font at 320 px

Signed-out Codex terminal

Verification

• Head 1c765685aa587a408b3b2c6386b943efef9d4ce0 is based on main at b883fc066ea5c9bebbe1c3e9b4bc2471aab3685f.
• 1,053 focused tests passed across 58 files. Typechecks passed for 4 affected packages.
• Latest-head CI completed with no failures, including Check, Test, Test Server 1-3, Rust, release smoke, native fingerprint, and the macOS preview build.
• Macroscope Correctness, Effect Service Conventions, and UI Consistency passed. Cursor completed neutral with no new findings. All 136 review threads are resolved. Approvability remains neutral and not approved because this broad change requires human review. GitHub reports a clean merge state.
• Warm real-quota checks passed with a fresh standard token. Cold-start checks passed with a fresh admin token. Together they passed all 59 checks.
• A 79-check session-isolation run paired 2 environments at 2 origins in one browser context. Both environments kept the correct cookie and session after reload, with 0 page, request, or HTTP errors.
• The final browser pass produced 13 screenshots on this head from true fresh first-run flows in light and dark contexts. Only Codex and Claude Code appeared, and both were ready. The run covered Back, Skip, invalid direct pairing, reload, retry, and completion with 0 page, request, or HTTP errors and 0 live turn starts.
• The scan found 17 project candidates. The selected project exposed 6 thread candidates; the run imported 4 and reported 1 skipped. The disposable database contained 1 project, 4 threads, and 25 messages. Completion restored the saved 20 px font, 150% contrast, theme, and selected project target. The 320 px and 1,440 px layouts had no overflow or overlap.
• A 49-check recovery and theme run passed in a light browser. It verified no app flash, the black and white palette, hover and focus states, and the black focus-ring offset, with 0 page, request, or HTTP errors.
• A real custom-theme run cleared the active palette during onboarding, restored it afterward, and verified the Settings card and tooltip with 0 page, request, or HTTP errors.
• A real provider-settings run saved a sensitive environment value. Settings and terminal metadata stayed redacted. The PTY received the configured secret and CODEX_HOME, did not receive T3CODE_PORT, and cleaned up after close. No login command or provider turn was submitted.
• A legacy-only signed-out Codex PTY run on this head produced 3 screenshots. It preset the configured binary login command without submitting it, rendered a nonblank terminal, passed dark menu focus and hover checks at desktop and mobile sizes, and cleaned up after close.
• Shared browser verification used supported T3CODE_BUNDLED_DEV=0. The experimental bundled dev server can reload after its first build and cancel pairing.
• Native macOS desktop and mobile UI were not exercised on Linux.

Built with GPT-5.6 Sol in Codex.

Note

Changes since #5362 opened

• Modified AgentSessionScanner transcript discovery to enforce a unified operation budget covering both directory reads and file stats, and filter out non-file entries during discovery and before reading transcripts [1c76568]
• Added support for legacy provider instances in terminal.resolveProviderInstanceTerminalEnvironment by importing and using deriveProviderInstanceConfigMap to source provider instance configurations [1c76568]
• Implemented history import tracking by adding an optional historyImport field to ThreadCreateCommand schema, propagating it through AgentSessionImporter.importRecentAgentThreads, and conditionally injecting metadata.historyImport: true into thread.created events in the orchestration decider [1c76568]
• Modified AgentAwarenessRelay.shouldPublishAgentAwarenessEvent to suppress publication of any event with metadata.historyImport set to true [1c76568]
• Refactored shared.compareDateTimeStrings to consistently sort malformed date-time strings before valid ones by parsing both values once and comparing based on validity [1c76568]

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 92f201e6-0378-4f3c-be90-a488d2038d3c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Warning

Your free Security trial is over. An organization admin can activate Security or dismiss this notice.

---

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Effect service conventions review of the new agent-session scanner service, its contract error, and the WS wiring. Three convention violations found; details inline.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR introduces a large first-run onboarding, agent setup, transcript import, and resumable-session workflow with substantial UI, filesystem, persistence, terminal, lifecycle, and authorization changes. It also changes product defaults and adds a static-analysis suppression, so the scope and sensitive runtime effects require human review.

^{You can add or adjust custom eligibility rules. Learn more.}

[macroscopeapp]

One convention issue found in the new server service module. The three items flagged on the previous revision (redundant failure singleton on AgentSessionScanError, message-derived wrapper in ws.ts, unexported make) are all resolved.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Effect service conventions review of the new AgentSessionScanner service and its RPC wiring. The three findings from the previous run (namespace import for ProjectionSnapshotQuery, structural operation discriminator on the scan error, exported make) are all addressed. Two remaining items below.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

One remaining convention deviation on the new contract error; everything else (namespace imports, single-module service layout with inline interface + make/layer, environment-based dependency acquisition, Foo["Service"] usage) looks consistent with the conventions.

^{Posted via Macroscope — Effect Service Conventions}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	13.2 KiB	13.3 KiB	+64 B (+0.5%)	15.1 KiB	✅
Codex	Thread snapshot wire	6.9 KiB	6.9 KiB	0 B (0.0%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	6.3 KiB	6.4 KiB	+64 B (+1.0%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	55.5 KiB	55.6 KiB	+88 B (+0.2%)	66.4 KiB	✅
Codex	Live turn messages	8	10	+2 (+25.0%)	21	✅
Claude	Total thread wire	13.2 KiB	13.5 KiB	+216 B (+1.6%)	15.1 KiB	✅
Claude	Thread snapshot wire	6.9 KiB	6.9 KiB	+2 B (+0.0%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	6.4 KiB	6.6 KiB	+214 B (+3.3%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	56.3 KiB	57.8 KiB	+1.5 KiB (+2.7%)	66.4 KiB	✅
Claude	Live turn messages	8	10	+2 (+25.0%)	21	✅

Baseline: b883fc0 · PR result: 1c76568 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 109.4 KiB
• Claude decoded thread snapshot: 110.1 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[EClinick]

Oh lets go, super hyped for this

[t3dotgg]

Note

🤖 GPT-5.6 Sol responding on behalf of Theo

@macroscope-app manual review

Please review current head 0bc3b99557aff668816dc9fe22097403c3996094. The automatic correctness review was skipped because its estimated cost of $11.25 exceeded the $10.00 per-review limit.

[macroscopeapp]

Manual review triggered for the current head; checks are in progress.