chore: sync with upstream/main (58e60bf5e)

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

@@ -21,6 +21,19 @@ Test with meaningful project and thread data. Read
 [references/sqlite-fixtures.md](references/sqlite-fixtures.md) only when
 inspecting or seeding SQLite. Stop the test server before direct fixture writes.
 
+## Drive agent turns for free
+
+Do not spend a paid model to see a turn render. `vp run dev` registers the
+`Replay (dev)` provider, which replays recorded turns with simulated streaming
+through the real adapter and orchestration. Its models are scenarios:
+`showcase` covers thinking, a plan, tool calls, an approval, and markdown.
+Press `Ctrl+Alt+Shift+R` for a picker (GNOME takes that key for screen
+recording), call `window.t3dev.replay("showcase")`
+with `preview_evaluate`, or run
+`node apps/server/src/bin.ts thread start --base-dir .t3 --provider devReplay --model showcase <project> "go"`.
+When the test needs real provider behavior, use that provider's cheapest
+model, such as Haiku for Claude or Luna for Codex.
+
 ## Use the Browser panel
 
 Call `preview_status`, then `preview_open` if the Browser panel is

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

@@ -38,8 +38,8 @@ This installs the dev client for the checkout's native fingerprint: from the
 device, the local cache, or the shared cache in seconds, building once only
 when no machine has that fingerprint yet (5-15 minutes, logged to the file it
 names). The device id may be omitted when exactly one device is booted. It
-prints one JSON line; on failure it names the next command. Authorized mobile
-verification includes that step unless the user prohibits it.
+prints one JSON line; on failure it names the next command. Mobile verification
+includes that step unless the user prohibits it.
 
 For a device you opened in an agent-device session elsewhere (a device pool,
 cloud, or remote host), run `vp run mobile:install <ios|android> --session <s>`

.coderabbit.config.ts

@@ -26,13 +26,19 @@ export default defineConfig((ctx) => ({
         path: "apps/web/src/**/*.{tsx,css}",
         instructions: "Hold changed code to the rules in docs/internals/web-ui.md.",
       },
+      {
+        path: "**/*.test.*",
+        instructions:
+          "Hold changed tests to the rules in docs/internals/testing.md. Request tests only as those rules allow.",
+      },
     ],
   },
   knowledge_base: {
     code_guidelines: {
       filePatterns: [
         { files: "docs/internals/effect-services.md", applyTo: "{apps,packages,infra}/**/*.ts" },
         { files: "docs/internals/web-ui.md", applyTo: "apps/web/src/**/*.{tsx,css}" },
+        { files: "docs/internals/testing.md", applyTo: "{apps,packages,infra}/**/*.{ts,tsx}" },
       ],
     },
   },

.github/VOUCHED.td

@@ -59,6 +59,7 @@ github:myacoub91
 github:naMqe-h
 github:nateEc
 github:naveed949
+github:nexxeln
 github:nmggithub
 github:Noojuno
 github:notkainoa

.github/actions/setup-ci-deps/action.yml

@@ -5,6 +5,14 @@ inputs:
     description: Read-only credential for the private maintainer task cache
     required: false
     default: ""
+  install:
+    description: Set to "false" to set up Vite+ only, with no pnpm store or install
+    required: false
+    default: "true"
+  install-args:
+    description: Arguments for `vp install`, such as filters. Empty installs the whole workspace.
+    required: false
+    default: ""
 runs:
   using: composite
   steps:
@@ -19,10 +27,11 @@ runs:
         echo "node=$(jq -r '.engines.node' package.json)" >> "$GITHUB_OUTPUT"
         echo "pnpm=$(jq -r '.packageManager' package.json)" >> "$GITHUB_OUTPUT"
 
+    # Pinned because release-desktop.yml signs builds with this action in the job.
     - name: Cache Vite+
       id: vp_cache
       if: steps.vp.outputs.version != ''
-      uses: actions/cache@v6
+      uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6
       with:
         path: ~/.vite-plus
         key: vite-plus-home-v2-${{ runner.os }}-${{ runner.arch }}-${{ steps.vp.outputs.version }}-node${{ steps.vp.outputs.node }}-${{ steps.vp.outputs.pnpm }}
@@ -38,38 +47,93 @@ runs:
         echo "$HOME/.vite-plus/bin" >> "$GITHUB_PATH"
         "$HOME/.vite-plus/bin/vp" env use "${{ steps.vp.outputs.node }}"
 
+    # vp gives each Node.js download attempt 10 minutes by default, so one
+    # stalled stream holds the job that long. It retries 3 times and resumes
+    # partial bytes, so a shorter limit costs a slow download only a retry.
     - name: Setup Vite+
       if: steps.vp_cache.outputs.cache-hit != 'true'
-      uses: voidzero-dev/setup-vp@v1
+      uses: voidzero-dev/setup-vp@250f29ce396baf5e8f24498e17c0dfdebabc26eb # v1
+      env:
+        VP_DOWNLOAD_TIMEOUT: "120"
       with:
         node-version-file: package.json
         cache: false
         run-install: false
 
-    - name: Resolve pnpm store path
+    # A shared key lets whichever install saves first, often a small filtered
+    # one, become every job's store. Each set of install args gets its own.
+    - name: Resolve pnpm store
       id: pnpm_store
+      if: inputs.install == 'true'
       shell: bash
+      env:
+        INSTALL_ARGS: ${{ inputs.install-args }}
       run: |
-        store_path="$(vp pm cache dir)"
-        echo "path=$store_path" >> "$GITHUB_OUTPUT"
+        echo "path=$(vp pm cache dir)" >> "$GITHUB_OUTPUT"
+        metadata_dir="${pnpm_config_cache_dir:-$RUNNER_TEMP/pnpm-metadata}"
+        echo "pnpm_config_cache_dir=$metadata_dir" >> "$GITHUB_ENV"
+        echo "verified=$metadata_dir/lockfile-verified.jsonl" >> "$GITHUB_OUTPUT"
+        if [[ -z "$INSTALL_ARGS" ]]; then
+          echo "namespace=full" >> "$GITHUB_OUTPUT"
+        else
+          echo "namespace=filtered-$(printf '%s' "$INSTALL_ARGS" | cksum | cut -d' ' -f1)" >> "$GITHUB_OUTPUT"
+        fi
 
-    # setup-vp's shared cache key ignores install filters. Keep full installs in a
-    # separate namespace, including fallback restores.
+    # Filtered installs prefer the current full store, which holds every package,
+    # over an older store of their own.
     # The pnpm store stays a cache tarball on the runner's own disk. A store on a
     # Blacksmith sticky disk mounts in under a second, but pnpm then copies every
     # package across filesystems instead of hard-linking it: install took 28-49s
     # against 9s plus an 11s restore.
-    - name: Cache full pnpm store
-      uses: actions/cache@v6
+    - name: Restore pnpm store
+      id: pnpm_cache
+      if: inputs.install == 'true'
+      uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6
       with:
         path: ${{ steps.pnpm_store.outputs.path }}
-        key: pnpm-full-v1-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('pnpm-lock.yaml', 'pnpm-workspace.yaml', 'package.json') }}
+        key: pnpm-${{ steps.pnpm_store.outputs.namespace }}-v1-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('pnpm-lock.yaml', 'pnpm-workspace.yaml', 'package.json') }}
         restore-keys: |
+          pnpm-full-v1-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('pnpm-lock.yaml', 'pnpm-workspace.yaml', 'package.json') }}
+          pnpm-${{ steps.pnpm_store.outputs.namespace }}-v1-${{ runner.os }}-${{ runner.arch }}-
           pnpm-full-v1-${{ runner.os }}-${{ runner.arch }}-
 
+    # pnpm accepts an earlier pass for the same lockfile and policy at any age, so
+    # a cached record skips fetching registry metadata for every package.
+    - name: Restore lockfile verification
+      id: pnpm_verified
+      if: inputs.install == 'true'
+      uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6
+      with:
+        path: ${{ steps.pnpm_store.outputs.verified }}
+        key: pnpm-verified-v1-${{ hashFiles('pnpm-lock.yaml', 'pnpm-workspace.yaml', 'package.json') }}
+
     - name: Install dependencies
+      if: inputs.install == 'true'
       shell: bash
-      run: vp install
+      env:
+        INSTALL_ARGS: ${{ inputs.install-args }}
+      # Unquoted so each filter is its own argument.
+      run: vp install $INSTALL_ARGS
+
+    - name: Save lockfile verification
+      if: inputs.install == 'true' && steps.pnpm_verified.outputs.cache-hit != 'true'
+      uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6
+      with:
+        path: ${{ steps.pnpm_store.outputs.verified }}
+        key: ${{ steps.pnpm_verified.outputs.cache-primary-key }}
+
+    # A filtered install that started from the current full store adds nothing
+    # worth a second copy of it.
+    - name: Save pnpm store
+      if: >-
+        inputs.install == 'true' &&
+        steps.pnpm_cache.outputs.cache-hit != 'true' &&
+        (steps.pnpm_store.outputs.namespace == 'full' ||
+          steps.pnpm_cache.outputs.cache-matched-key != format('pnpm-full-v1-{0}-{1}-{2}', runner.os, runner.arch, hashFiles('pnpm-lock.yaml', 'pnpm-workspace.yaml', 'package.json')))
+      uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6
+      with:
+        path: ${{ steps.pnpm_store.outputs.path }}
+        key: ${{ steps.pnpm_cache.outputs.cache-primary-key }}
 
     - name: Enable shared task cache
       if: >-

.github/scripts/ci-changes.cjs

@@ -32,6 +32,8 @@ const RUST = /^native\/(resource-monitor|kde-snap-shot|hyprland-snap-shot)\//;
 
 // These tests read other packages without declaring dependencies.
 const TEST_ONLY_DEPS = {
+  // Evals import the server's source to test its real model-facing text.
+  "@t3tools/evals": ["t3"],
   "@t3tools/provider-pi": ["@t3tools/client-runtime"],
   "@t3tools/scripts": [
     "@t3tools/desktop",

.github/triage/PLAYBOOK.md

@@ -11,8 +11,8 @@ provided alongside this playbook. Everything machine-specific lives there, not h
 
 ## 1. Ask what went wrong
 
-Your first message to the user: ask them to describe what went wrong, in their own
-words. Ask them to paste screenshots directly into this session if they have any.
+Unless the user already described it, your first message asks what went wrong, in
+their own words. Ask them to paste screenshots directly into this session if they have any.
 Ask follow-up questions when the description is vague. Good repro steps are the most
 valuable thing you can extract from this conversation.
 

.github/workflows/ci.yml

@@ -168,6 +168,12 @@ jobs:
       - name: Test
         run: vp run --filter @t3tools/web test --maxWorkers=1 --testTimeout=60000
 
+      # Browser tests run source modules; this boots the production chunk graph.
+      - name: Boot the built web client
+        run: |
+          vp run --filter @t3tools/web build
+          node apps/web/scripts/verify-built-boot.ts
+
   # apps/server sets `fileParallelism: false`, so its test files run strictly
   # one at a time. Sharding spreads them over separate runners instead of
   # separate workers, so no two server test files ever share a machine and the

.gitignore

@@ -37,6 +37,7 @@ apps/mobile/.android-cache/
 /.generated/
 artifacts/app-store/screenshots/
 artifacts/mobile-e2e/
+artifacts/mobile-behavior/
 .github/pr-assets/
 native/**/target/
 node_modules/

.macroscope/check-run-agents/effect-service-conventions.md

@@ -1,7 +1,7 @@
 ---
 title: Effect Service Conventions
-model: gpt-6-sol
-effort: max
+model: gpt-6-1-sol
+reasoning: low
 input: incremental
 tools:
   - browse_code

.macroscope/check-run-agents/test-signal.md

@@ -0,0 +1,27 @@
+---
+title: Test Signal
+model: gpt-6-1-terra
+reasoning: low
+input: incremental
+tools:
+  - browse_code
+  - modify_pr
+# An explicit include overrides ignore.md, which skips test files for every other check.
+include:
+  - "**/*.test.*"
+exclude:
+  - ".repos/**"
+requires:
+  - Check
+maxBudgetPerRun: 1
+maxBudgetPerPR: 5
+conclusion: neutral
+---
+
+# Test signal review
+
+Review only the tests this pull request adds or grows. Tests it moves, renames, or deletes are not findings. The rules are in `docs/internals/testing.md` under `## What to test`; read that section first and hold new tests to it.
+
+Post each finding as a brief inline comment on the new test with one fix. Ask only for fewer or smaller tests, never for more coverage.
+
+When there are no findings, make the entire final response exactly `All clear` on one line with nothing else.

.macroscope/check-run-agents/ui-consistency.md

@@ -1,7 +1,7 @@
 ---
 title: UI Consistency
-model: gpt-6-sol
-effort: max
+model: gpt-6-1-sol
+reasoning: low
 input: incremental
 tools:
   - browse_code

AGENTS.md

@@ -98,14 +98,17 @@ An empty database is a bad test. Seed your worktree's `.t3` with a copy of real
 
 ## Verifying
 
-- Before you push, run `vp run check:changed`. It runs CI's fast checks for changed files: format, lint, knip, typecheck of affected packages and dependents, and tests beside changes. CI still runs the full test suites.
+- Before you push, run `vp run check:changed`. It runs CI's fast checks for changed files: format, lint, knip, typecheck of affected packages and dependents, tests beside changes, and the cross-file checks those miss. CI still runs the full test suites.
 - While you iterate, run `vp test run <files>`. For big files, add `-t "<name>"`.
 - Use `vp run typecheck`, not `npx tsc`; it caches per package. Both run tsc-rs (`typescript` is the `@tsc-rs/typescript` drop-in).
 - Run `node -e` snippets from `apps/server` or the owning package. `effect` does not resolve from the repo root.
-- Test meaningful logic or observable behavior. Do not render components to static markup to assert props or attributes, or add tests that merely assert callback wiring or mirror the implementation.
+- Test behavior that can break, such as orchestration and event-sourcing, provider protocol translation, auth and permission guards, persistence and migrations, external-format parsing, race fixes, and the logic a bug fix changed. Leave out tests for what types already guarantee, trivial logic, copy text, smoke runs, mock-call mirrors, callback wiring, and props rendered to static markup.
+- Extend before you add. When an existing test or table covers the behavior, add a row or an assertion there. Write a new `it` only when no case fits.
+- Test at one layer: the lowest one that fails on `main`. Do not repeat the case in a wrapper test, at each call site, or in web and mobile copies of the same logic.
+- [Testing](docs/internals/testing.md) carries these same test rules, plus review guidance, for review bots. Change both together.
 - **Do not run repo-wide checks.** No `vp check`, no `vp run -r test`, no `vp run -r typecheck` unless I ask. CI owns the full suite.
 - Backend behavior changes ship with focused tests for that behavior.
-- Proof for a bug fix depends on the bug. Logic, data, state, and protocol bugs get a failing test first (the fewest that fail on `main` for that reason, in the module's existing test file), then the fix. Purely visual bugs (spacing, colour, alignment, a layout shift) get before/after captures as their proof and no test: do not add UI tests for nitpicks, and do not ask for one in review when a capture already shows it. A server-only fix with no visible surface ships the test plus a short runtime transcript.
+- Proof for a bug fix depends on the bug. Logic, data, state, and protocol bugs get a failing test first (the fewest that fail on `main` for that reason, in an existing case of the module's test file where one fits), then the fix. Purely visual bugs (spacing, colour, alignment, a layout shift) get before/after captures as their proof and no test: do not add UI tests for nitpicks, and do not ask for one in review when a capture already shows it. A server-only fix with no visible surface ships the test plus a short runtime transcript.
 - The server is event-sourced, and side effects run after the command commits. In tests, drain the effect worker (`OrchestrationEffectWorkerV2.drain`) or await the specific persisted event or `Deferred` that marks the milestone. Never wait on sleeps or polling. A test that needs a timeout to pass is wrong. Concretely:
   - `it.effect` runs on a `TestClock`; `Effect.sleep` only advances through `TestClock.adjust`. `it.live` is wall-clock and only for subprocess or network fixtures.
   - No `yieldNow` or `sleep` polling loops. Await the `Deferred`, take from the `Queue`, or drain the worker.
@@ -133,9 +136,15 @@ An empty database is a bad test. Seed your worktree's `.t3` with a copy of real
   });
   ```
 
-- Upon request, user-visible frontend changes should get one integrated pass in a real client: `test-t3-app` for web, `test-t3-mobile` for mobile. The primary agent does this once after integrating. Subagents do not launch their own dev servers. Ask permission before doing computer use or spinning up browsers.
+- User-visible frontend changes should get one integrated pass in a real client: `test-t3-app` for web, `test-t3-mobile` for mobile. The primary agent does this once after integrating. Subagents do not launch their own dev servers.
 
-For authorized mobile verification, a missing or outdated native client is an install step, not a blocker. Run `vp run mobile:install <ios|android> [device-id]` on the device host before starting Metro; it targets the only booted simulator or connected Android device when the id is omitted. It installs the dev client for this checkout's native fingerprint from the shared cache in seconds and builds only when no machine has built it yet, so prefer it over `expo run:*`, `xcodebuild`, or `gradlew`, which rebuild from scratch. Its stdout is one JSON line; build output goes to the log it names. See `test-t3-mobile` for the full workflow.
+- Real agent turns cost money. To watch a turn stream through the pipeline and UI, use the free `Replay (dev)` provider that `vp run dev` registers; [test-t3-app](.agents/skills/test-t3-app/SKILL.md) shows how to start one. Use a real provider only when the change depends on that provider's behavior, and then pick its cheapest model, such as Haiku for Claude or Luna for Codex.
+
+For mobile verification, a missing or outdated native client is an install step, not a blocker. Run `vp run mobile:install <ios|android> [device-id]` on the device host before starting Metro; it targets the only booted simulator or connected Android device when the id is omitted. It installs the dev client for this checkout's native fingerprint from the shared cache in seconds and builds only when no machine has built it yet, so prefer it over `expo run:*`, `xcodebuild`, or `gradlew`, which rebuild from scratch. Its stdout is one JSON line; build output goes to the log it names. See `test-t3-mobile` for the full workflow.
+
+## Evals
+
+`evals/` checks how real models behave with T3 Code's model-facing text: agent instructions, MCP tool descriptions and schemas, and generated titles. Before you change that text, read [evals/README.md](evals/README.md) and run the evals it names. When you fix a model behavior bug, add a case that fails before the fix.
 
 ## Pull requests
 
@@ -197,13 +206,12 @@ Architecture and its constraints: `docs/internals/overview.md`. Glossary: `docs/
   options, and pass combinators as additional function-builder arguments.
 - Inferred types over annotations. `any` is the enemy.
 - Default to no comment. Write one only for a constraint, an external quirk, or an invariant the code can't show, in one line where you can and four at most. Don't restate names or signatures, narrate steps, record history, or explain the fix you just made; the PR carries that. `t3code/no-low-value-comments` enforces the length cap and the mechanical cases.
-- React effects are for synchronizing with something outside React. Derive in render and act in handlers instead of syncing state, but don't hide real lifecycle work in refs or stores to dodge one. The `t3code/react-effect-budget` lint rule holds each file to its count in `scripts/effect-budget.json`; a new effect states its reason with `// oxlint-disable-next-line t3code/react-effect-budget -- <why>`.
+- React effects are for synchronizing with something outside React. Derive in render and act in handlers instead of syncing state, but don't hide real lifecycle work in refs or stores to dodge one. The `t3code/no-unreasoned-state-sync` lint rule reports every effect; one that stays states its reason with `// oxlint-disable-next-line t3code/no-unreasoned-state-sync -- <why>`.
 - Our users drive agents all day and notice a dropped frame, a lying spinner, and a stale label. No continuously repainting animations; they peg the GPU on high-refresh displays.
 - If a rule here fights the task in front of you, say so loudly and get a human sign-off before breaking it.
 
 ## Additional tips
 
-- Don't verify with browsers or computer use unless the user explicitly agrees or requests it.
 - Security is important, but should not be over-indexed on, especially for dev mode/maintainer-only features.
 
 ## Agent skills