The best way to control Claude Code, Codex and more from any computer or phone
fix(dev): dev runner never points a dev server at the live ~/.t3/userdata (#38807)
Co-authored-by: Julius Marminge <julius0216@outlook.com>
Lenori committed
Nov 19, 2026 at 21:14 UTC
4c099280f60022e0d099afb8071fed0cd3bdb042
4 files changed
+20
-4
AGENTS.md
+1
-1
@@ -80,7 +80,7 @@ The most common defect in this repo is a change that works on the path you teste
80
81
- `vp i` installs. Worktrees get this from the t3.json setup script; if module resolution looks broken, it probably did not run.
82
- Setup runs in the background. While `.t3/setup-running` names a live PID, wait for it and do not run `vp i`. It ends with `.t3/setup-done` or `.t3/setup-failed` (with the error tail). With no marker at all, setup never ran here, so run `vp i` yourself.
83
-- `vp run dev` starts server and web. In a worktree, state defaults to that worktree's gitignored `.t3`, which deliberately outranks an ambient `T3CODE_HOME` so you cannot land on shared state by accident. An explicit `--home-dir` still wins.
83
+- `vp run dev` starts server and web. In a worktree, state defaults to that worktree's gitignored `.t3`, which deliberately outranks an ambient `T3CODE_HOME` so you cannot land on shared state by accident. An explicit `--home-dir` still wins. A plain `git clone` is not a worktree: it shares `~/.t3/dev` with the main checkout and is not seeded. To isolate one, run `vp run migrate-dev-db --base-dir <clone>/.t3`, then `vp run dev --home-dir <clone>/.t3`.
84
- Ports derive from the worktree path and are stable across restarts, but read the real ones from the `[dev-runner]` line since occupied ports shift.
85
- Sharing over the tailnet is three steps: run `vp run dev --share` in the background, wait for the `pairingUrl:` line in its output, then give that full URL to an unpaired browser. Do not wire up `tailscale serve` by hand, open the URL yourself, or consume the user's pairing link. A browser with the reusable dev cookie can use the bare origin. If a normal one-time token was consumed, mint a fresh one with `node apps/server/src/bin.ts pair`. It carries standard scopes, while the startup URL carries admin scopes needed for Connections settings.
86
- To reuse web dev auth across worktrees, configure one fixed `T3CODE_DEV_AUTH_TOKEN` in the main checkout's gitignored `.env`. The `t3.json` setup links that file into worktrees. Never commit or publish the token or a startup URL. See [Reusable dev credential](docs/operations/development.md#reusable-dev-credential).
docs/operations/development.md
+10
-1
@@ -60,10 +60,19 @@ Running `vp run dev` through an agent's own shell tool does not attach it to thi
60
### State and ports
61
62
Linked worktrees default to their own `.t3/userdata`, even when `T3CODE_HOME` is set.
63
-The main checkout defaults to `~/.t3/dev`. An explicit `--home-dir` wins in both cases.
63
+Any other checkout, including the main checkout and every plain `git clone`, uses
64
+`T3CODE_HOME` when it is set and otherwise `~/.t3/dev`, with default ports. Checkouts on
65
+`~/.t3/dev` share one database, settings, and secrets, and only one of their servers can run
66
+at a time. An explicit `--home-dir` wins in both cases. It and `T3CODE_HOME` store state in
67
+`<home>/userdata`.
68
+A home of `~/.t3`, from either source, still selects `~/.t3/dev`, because `~/.t3/userdata` is
69
+the live install.
70
The first start in a worktree seeds its empty database from a read-only copy of
71
`~/.t3/userdata/statev2.sqlite` if the source is at most 500 MiB. Larger sources warn
72
and dev starts with an empty database. `--no-seed` or `T3CODE_DEV_SEED=0` skips seeding.
73
+Seeding targets only a worktree's own `.t3`, so a plain clone or a `--home-dir` outside the
74
+worktree starts empty. To give a clone its own seeded state, run
75
+`vp run migrate-dev-db --base-dir <clone>/.t3` and then `vp run dev --home-dir <clone>/.t3`.
76
To copy a larger source, run `vp run migrate-dev-db` with dev stopped. It may use
77
substantial disk space before pruning.
78
The first start in any checkout also builds the native resource monitor with Cargo when
scripts/dev-runner.test.ts
+4
-1
@@ -549,6 +549,9 @@ it.layer(NodeServices.layer)("dev-runner", (it) => {
549
assert.equal(yield* homeFor("~someone/t3-dev"), path.resolve("~someone/t3-dev"));
550
assert.equal(yield* homeFor("relative/t3-dev"), path.resolve("relative/t3-dev"));
551
assert.equal(yield* homeFor("/tmp/t3-dev"), path.resolve("/tmp/t3-dev"));
552
+ // An explicit ~/.t3 would put state in the live userdata; leaving it implicit selects ~/.t3/dev.
553
+ assert.equal(yield* homeFor("~/.t3"), undefined);
554
+ assert.equal(yield* homeFor("/home/dev/.t3/"), undefined);
555
}),
556
);
557
@@ -795,7 +798,7 @@ it.layer(NodeServices.layer)("dev-runner", (it) => {
798
Effect.provideService(HostProcess.Platform, "linux"),
799
Effect.provideService(HostProcess.WorkingDirectory, input.cwd),
800
// No ~/.t3 here, so these runs never seed from this machine's install.
798
- Effect.provideService(HostProcess.HomeDirectory, input.cwd),
801
+ Effect.provideService(HostProcess.HomeDirectory, NodePath.join(input.cwd, "home")),
802
Effect.provideService(
803
HostProcess.Environment,
804
input.ambientHome === undefined ? {} : { T3CODE_HOME: input.ambientHome },
scripts/dev-runner.ts
+5
-1
@@ -329,7 +329,11 @@ export const createDevRunnerEnv = Effect.fn("dev-runner.createDevRunnerEnv")(fun
329
`http://${isDesktopMode ? DESKTOP_DEV_LOOPBACK_HOST : "localhost"}:${webPort}`,
330
};
331
332
- if (configuredBaseDir !== undefined) {
332
+ const path = yield* Path.Path;
333
+ // The server stores an explicit home's state in userdata, which for ~/.t3 is the live
334
+ // install. Left implicit, dev state goes to ~/.t3/dev.
335
+ const isLiveHome = resolvedBaseDir === path.join(yield* HostProcess.HomeDirectory, ".t3");
336
+ if (configuredBaseDir !== undefined && !isLiveHome) {
337
output.T3CODE_HOME = resolvedBaseDir;
338
} else {
339
delete output.T3CODE_HOME;