merge: upstream through 6f34ad3e8 (2026-07-21) — pre-Sidebar-v2 cut

.agents/skills/ios-debugger-agent/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) OpenAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

.agents/skills/ios-debugger-agent/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: ios-debugger-agent
+description: Build, launch, inspect, and drive iOS apps with the repository-configured XcodeBuildMCP server. Use on macOS for iOS Simulator builds, focused native test runs, semantic UI automation, screenshots, logs, or debugging, including T3 Code Mobile verification.
+---
+
+# iOS Debugger Agent
+
+Use the repository-configured `xcodebuildmcp` tools instead of requiring a globally installed Codex plugin. Prefer MCP tools over raw `xcodebuild`, `xcrun`, or `simctl` when the client exposes them.
+
+## Confirm availability
+
+This workflow requires macOS 14.5 or newer, Xcode 16 or newer, and Node.js 18 or newer. The repository pins XcodeBuildMCP in both `.mcp.json` for Claude Code and `.codex/config.toml` for Codex. Project MCP servers may require one-time trust or approval followed by a new session.
+
+If the tools are missing:
+
+1. Confirm the repository is trusted and its project MCP server was approved.
+2. Restart or recreate the agent session after approving configuration.
+3. Run `npx --yes xcodebuildmcp@2.6.2 doctor` when the server starts but simulator or UI-automation tools are unavailable. Follow its actionable Xcode or AXe setup guidance.
+4. Fall back to the pinned XcodeBuildMCP CLI or native Apple CLIs only when the current agent client cannot expose project MCP tools.
+
+Do not ask contributors to install the OpenAI `build-ios-apps` plugin globally.
+
+## Establish one simulator context
+
+1. Call `session_show_defaults` before discovery, build, launch, or UI work.
+2. Call `list_sims` and select one explicit simulator UDID. Prefer a simulator that is already booted; boot an installed simulator when verification requires it, but do not create or download runtimes without user authorization.
+3. Call `session_set_defaults` with the project or workspace, scheme, Debug configuration, simulator ID, and bundle identifier when known.
+4. Keep every subsequent build, launch, screenshot, log capture, and UI action pinned to that same UDID.
+
+Avoid generic Mac window automation for switching among Simulator windows. Explicit device identity is more reliable.
+
+## Choose build or launch
+
+- Use `build_run_sim` when native source, native dependencies, entitlements, or project configuration changed.
+- Use `test_sim` for the smallest relevant native test target or test cases; do not run an entire workspace test matrix routinely.
+- Use `launch_app_sim` when a compatible app is already installed and no native rebuild is needed.
+- To reuse an existing build artifact, use `get_sim_app_path` or `get_app_bundle_id`, install it with `install_app_sim` when necessary, and then launch it.
+- Do not run a build-only action immediately before `build_run_sim` unless the task requires both artifacts.
+
+After launch, call `snapshot_ui` or `screenshot` before interacting. An open Simulator window alone is not evidence that the intended app launched.
+
+## Drive the UI semantically
+
+1. Call `snapshot_ui` to obtain the current accessibility hierarchy and element references.
+2. Use only current `elementRef` values whose snapshot entries list the intended action. XcodeBuildMCP `2.6.2` does not accept coordinates for `tap`; when the app exposes no actionable reference, prefer a registered deep link or another app-supported route and otherwise report the accessibility blocker.
+3. Refresh with `snapshot_ui` after navigation or layout changes. Element references are snapshot-specific.
+4. Use `wait_for_ui` for asynchronous transitions when available rather than fixed sleeps.
+5. Capture a final `screenshot` for the state that proves the affected flow.
+
+Use `gesture` or scoped swipe actions when needed. If a gesture is unreliable, return to a known route or relaunch rather than switching to generic desktop automation.
+
+## Capture logs and debug
+
+- Use `start_sim_log_cap` and `stop_sim_log_cap` with the exact bundle identifier for focused runtime logs.
+- Use debugger tools only when the task requires runtime diagnosis; attach to the selected simulator and app rather than an ambiguous process.
+- Summarize relevant errors instead of returning unbounded logs.
+
+## Clean up
+
+Stop only log captures, debugger sessions, apps, or simulators started for the current test. Leave pre-existing simulators and unrelated sessions alone.
+
+## Upstream
+
+Adapted from OpenAI's [`build-ios-apps`](https://github.com/openai/plugins/tree/main/plugins/build-ios-apps) plugin version `0.1.2` (`ios-debugger-agent`, MIT) and aligned with XcodeBuildMCP `2.6.2` tool names.

.agents/skills/ios-debugger-agent/agents/openai.yaml

@@ -0,0 +1,9 @@
+interface:
+  display_name: "iOS Debugger Agent"
+  short_description: "Build and drive iOS Simulator apps"
+  default_prompt: "Use $ios-debugger-agent to build, launch, and inspect the current iOS app on Simulator."
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "xcodebuildmcp"
+      description: "Repository-configured Xcode build, simulator, logging, debugging, and semantic UI tools"

.agents/skills/ios-simulator-browser/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) OpenAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

.agents/skills/ios-simulator-browser/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: ios-simulator-browser
+description: Stream an explicit iOS Simulator through pinned serve-sim into the T3 Code in-app browser or another agent browser. Use on Apple Silicon macOS when the user should watch simulator verification live or when browser-visible simulator evidence is needed.
+---
+
+# iOS Simulator Browser
+
+Use serve-sim as the shared visual feed for an iOS Simulator. Use `ios-debugger-agent` and XcodeBuildMCP semantic UI tools to drive the app; do not treat browser-canvas coordinates as a substitute for missing app accessibility.
+
+## Confirm availability
+
+serve-sim `0.1.45` requires Apple Silicon macOS, Xcode command-line tools, and Node.js 20 or newer. If the host is unsupported, continue with XcodeBuildMCP screenshots and report that live streaming was unavailable.
+
+When running inside T3 Code, use its product-native browser MCP to open the stream. Other agent hosts may use their own browser or preview surface.
+
+Keep serve-sim on its default `127.0.0.1` binding. Do not expose its preview to a LAN or tunnel unless the user explicitly requests that access and the network is trusted; the preview includes a token-gated shell-execution route.
+
+## Start one owned stream
+
+1. Obtain the exact simulator UDID from the iOS build or launch workflow.
+2. Check whether an existing serve-sim stream for that UDID belongs to another task. Reuse it only when explicitly shared; never kill another task's stream.
+3. Otherwise, clear only a stale stream for that UDID and start the pinned version with scoped cleanup:
+
+   ```bash
+   SIMULATOR_ID=<simulator-udid>
+   cleanup_serve_sim() {
+     npx --yes serve-sim@0.1.45 --kill "$SIMULATOR_ID" >/dev/null 2>&1 || true
+   }
+   trap cleanup_serve_sim EXIT INT TERM HUP
+   cleanup_serve_sim
+   npx --yes serve-sim@0.1.45 "$SIMULATOR_ID"
+   ```
+
+4. Keep the terminal alive and open the exact local URL printed by serve-sim in the agent's browser.
+5. Verify that a live simulator frame renders. A loaded wrapper page is not sufficient evidence.
+
+## Observe while driving semantically
+
+- Let the user watch the serve-sim stream while XcodeBuildMCP performs `snapshot_ui`, semantic taps, typing, gestures, and screenshots.
+- Keep the browser and Xcode tooling pinned to the same simulator UDID.
+- Do not switch to generic desktop automation or browser-canvas clicking merely because the stream is visible.
+
+If the in-app browser explicitly reports that previews are unavailable, do not install unrelated browser automation. Continue through XcodeBuildMCP, capture a simulator screenshot, report the unavailable live stream, and clean up the owned serve-sim process.
+
+## Finish
+
+Stop the long-running terminal and wait for its cleanup trap to finish. If it disappeared without cleanup, run `npx --yes serve-sim@0.1.45 --kill <simulator-udid>` for that exact simulator. Never run an unscoped `--kill`.
+
+## Upstream
+
+Adapted from OpenAI's [`build-ios-apps`](https://github.com/openai/plugins/tree/main/plugins/build-ios-apps) plugin version `0.1.2` (`ios-simulator-browser`, MIT). It invokes serve-sim `0.1.45` under its Apache-2.0 license without vendoring the package.

.agents/skills/ios-simulator-browser/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "iOS Simulator Browser"
+  short_description: "Stream iOS Simulator in the browser"
+  default_prompt: "Use $ios-simulator-browser to stream the selected iOS Simulator into the T3 Code in-app browser."

.agents/skills/test-t3-app/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: test-t3-app
+description: Launch and test the T3 Code web app in isolated development environments, including first-try browser authentication with one-time pairing URLs, pairing-token recovery, worktree-safe state directories, dev server lifecycle, and direct SQLite inspection or fixture seeding. Use when an agent needs to run T3 locally, test UI behavior in a browser, recover from an expired or consumed pairing token, isolate dev state, or prepare test data in state.sqlite.
+---
+
+# Test T3 App
+
+Use this skill for the web client. For iOS Simulator, Android Emulator, or physical-device testing against an isolated T3 backend, use the sibling [`test-t3-mobile`](../test-t3-mobile/SKILL.md) skill.
+
+## Start an isolated web environment
+
+1. Run commands from the repository root.
+2. Choose a base directory that belongs only to the current worktree or test:
+   - Use the repository's ignored `.t3` directory for reusable worktree-local state.
+   - Use `mktemp -d /tmp/t3code-test.XXXXXX` for disposable state and retain the printed absolute path.
+3. Start the full web stack with `vp run dev --home-dir <base-dir>`.
+4. Keep the terminal session alive and read the selected server port, web port, base directory, and pairing URL from its output.
+
+Treat a base directory as disposable only when it was created or deliberately selected for the current test. Never delete or directly seed the shared `~/.t3` directory. Prefer starting with a new temporary base directory over clearing state of uncertain ownership.
+
+The dev runner disables browser auto-open by default. Do not pass `--browser` during automated testing: an automatically opened page can consume the one-time bootstrap token before the controlled browser uses it.
+
+## Authenticate the browser on the first navigation
+
+1. Wait for the server log that says authentication is required and includes a URL ending in `/pair#token=...`.
+2. Use the controlled in-app browser or browser-automation surface available to the agent. Do not use a system-browser launch command during automated testing.
+3. Open that complete URL exactly once as the controlled browser's first navigation. Preserve the fragment and token verbatim.
+4. Wait for the pairing exchange and redirect to finish before navigating elsewhere.
+5. Continue in the same browser context so its stored bearer session remains available.
+
+Treat pairing URLs as secrets. Do not copy them into final responses, screenshots, committed files, or durable logs. A pairing token is short-lived and single-use; opening the URL in another browser or opening it twice can consume it.
+
+## Recover a consumed or expired pairing token
+
+Create another token against the same database and web URL as the running dev server:
+
+```bash
+T3CODE_PORT=<server-port> node apps/server/src/bin.ts auth pairing create \
+  --base-dir <base-dir> \
+  --dev-url <web-url> \
+  --base-url <web-url> \
+  --ttl 15m \
+  --label agent-ui-test
+```
+
+Use the `Pair URL` from this command once. Derive `<server-port>` and `<web-url>` from the current dev-runner output, including any automatically selected port offset. Setting `T3CODE_PORT` keeps the administrative CLI from probing for an unrelated free port.
+
+Always pass `--dev-url` for a dev-runner environment so the generated pairing URL uses the current web origin. An explicit base directory stores runtime state in `<base-dir>/userdata`; the `<base-dir>/dev` fallback is only used by an implicit dev home. Use `auth pairing list` to inspect active token metadata; it intentionally cannot reveal token secrets.
+
+## Inspect or seed SQLite state
+
+Read [references/sqlite-fixtures.md](references/sqlite-fixtures.md) before changing the database.
+
+- Use `node apps/server/scripts/t3-sqlite-state.ts query` for schema discovery and read-only checks.
+- Stop the dev server before using `node apps/server/scripts/t3-sqlite-state.ts exec`, then restart it with the same base directory.
+- Seed projection tables only for disposable UI fixtures. Use application commands and APIs when testing business behavior or projection correctness.
+- Use the auth CLI, not direct `auth_*` table edits, for pairing and sessions.
+
+The helper refuses to write to the shared `~/.t3` directory by default and creates a database backup before each mutation.
+
+## Finish the test
+
+Stop the dev process with its terminal interrupt. Preserve the isolated base directory when it contains useful reproduction evidence; otherwise remove only a path that was created for this test after resolving and verifying the exact target. A fresh isolated base directory is the safest reset when authentication, migrations, or fixture state becomes ambiguous.
+
+## Troubleshoot predictably
+
+- If the browser shows an unauthenticated pairing screen, issue a new token instead of retrying the consumed URL.
+- If the pairing URL is no longer visible, create a replacement token with both `--dev-url` and `--base-url`.
+- If the replacement token is rejected, verify that the CLI and server use the identical absolute base directory and web URL.
+- If the UI shows unexpected data, verify that every command uses the identical explicit base directory before editing anything.
+- If ports move because another instance is running, trust the current dev-runner output rather than assuming ports `13773` and `5733`.

.agents/skills/test-t3-app/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "T3 App Testing"
+  short_description: "Launch and seed isolated T3 test environments"
+  default_prompt: "Use $test-t3-app to launch an isolated T3 development environment and test it in the browser."

.agents/skills/test-t3-app/references/sqlite-fixtures.md

@@ -0,0 +1,58 @@
+# SQLite fixtures
+
+Load this reference only when inspecting or seeding local T3 state directly.
+
+## Select the correct database
+
+When `--base-dir` or `--home-dir` is explicit, runtime state lives under `<base-dir>/userdata` and the database path is `<base-dir>/userdata/state.sqlite`. The `<base-dir>/dev` state directory is only the fallback for an implicit development home, preventing an ordinary `vp run dev` from touching production state.
+
+Start the target runtime once before seeding so all migrations have run. Use an isolated base directory. Stop the server before writes to avoid racing application state or an active projection.
+
+## Use the helper
+
+List tables:
+
+```bash
+node apps/server/scripts/t3-sqlite-state.ts query \
+  --base-dir <base-dir> \
+  --sql "SELECT name FROM sqlite_schema WHERE type = 'table' ORDER BY name"
+```
+
+Inspect current columns before writing a fixture:
+
+```bash
+node apps/server/scripts/t3-sqlite-state.ts query \
+  --base-dir <base-dir> \
+  --sql "PRAGMA table_info(projection_threads)"
+```
+
+Apply a SQL fixture from a file:
+
+```bash
+node apps/server/scripts/t3-sqlite-state.ts exec \
+  --base-dir <base-dir> \
+  --file /tmp/t3-seed.sql
+```
+
+Use one statement per invocation for both `query` and `exec`; the helper wraps writes in a transaction and prints the backup path after a successful mutation. Use a single insert with multiple value rows when a fixture needs several records.
+
+## Seed projection data carefully
+
+The web UI primarily reads these projection tables:
+
+- `projection_projects`
+- `projection_threads`
+- `projection_thread_messages`
+- `projection_thread_activities`
+- `projection_thread_sessions`
+- `projection_turns`
+- `projection_pending_approvals`
+- `projection_thread_proposed_plans`
+
+Inspect `PRAGMA table_info(<table>)` and the current migrations under `apps/server/src/persistence/Migrations/` before constructing inserts. Keep identifiers unique, timestamps as ISO strings, JSON columns valid, and related project/thread/turn IDs consistent.
+
+For a substantial current example, inspect `seedDatabase` in `scripts/mobile-showcase-environment.ts`. Adapt its column set to the target database instead of assuming copied SQL remains current.
+
+Direct projection writes are appropriate for ephemeral visual states, edge-case counts, long titles, activity lists, and similar UI fixtures. They do not create a coherent orchestration event history. Do not modify `orchestration_events` unless the test specifically exercises projector internals, and do not use direct projection writes to claim backend business behavior works.
+
+Use the app's commands or APIs for behavior tests. Use `node apps/server/src/bin.ts auth ...` for auth state rather than editing `auth_pairing_links` or `auth_sessions`.