@devries-cameron20 / t3code-1 / commits / 2adda57f11
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

fix(server): t3 doctor holds off server launches and names the holder (#24963)

Co-authored-by: Julius Marminge <julius0216@outlook.com>

Victor committed Nov 12, 2026 at 16:07 UTC 2adda57f11111064c2fe9efbf71954c0db2e136a
4 files changed +140 -31
apps/server/src/cli/doctor.test.ts
+85 -17
@@ -1,24 +1,59 @@
1 +import * as NodeCrypto from "@effect/platform-node/NodeCrypto";
2 import * as NodeServices from "@effect/platform-node/NodeServices";
3 +import * as HostProcess from "@t3tools/shared/HostProcess";
4 import { assert, it } from "@effect/vitest";
5 import * as Console from "effect/Console";
6 import * as Effect from "effect/Effect";
7 +import * as FileSystem from "effect/FileSystem";
8 import * as Layer from "effect/Layer";
9 +import * as Path from "effect/Path";
10 import * as TestClock from "effect/testing/TestClock";
11
12 import * as BootService from "../cloud/bootService.ts";
13 import { runDoctor } from "./doctor.ts";
14 import { DatabaseMaintenance } from "../persistence/DatabaseMaintenance.ts";
15 +import * as ProcessRunner from "../processRunner.ts";
16 +import { acquireServerOwnership } from "../serverOwnership.ts";
17 +import { makePersistedServerRuntimeState } from "../serverRuntimeState.ts";
18 +
19 +// An empty home, so no boot service unit installed on this machine is read.
20 +const layerHost = Layer.mergeAll(
21 + ProcessRunner.layer,
22 + Layer.effect(
23 + HostProcess.HomeDirectory,
24 + Effect.gen(function* () {
25 + return yield* (yield* FileSystem.FileSystem).makeTempDirectoryScoped();
26 + }),
27 + ),
28 + Layer.succeed(HostProcess.Environment, {}),
29 +).pipe(Layer.provideMerge(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer)));
30
31 it.effect(
13 - "--fix reclaims space with the service paused and keeps the V1 database, and --dry-run changes nothing",
32 + "--fix locks the home while the service is paused, names a server that holds it, keeps the V1 database, and --dry-run changes nothing",
33 () =>
34 Effect.gen(function* () {
35 + const fs = yield* FileSystem.FileSystem;
36 + const path = yield* Path.Path;
37 + const stateDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-doctor-" });
38 + const serverRuntimeStatePath = path.join(stateDir, "server-runtime.json");
39 const calls: string[] = [];
40 + const services =
41 + yield* Effect.context<Effect.Services<ReturnType<typeof acquireServerOwnership>>>();
42 + // Stands in for a server launched for the same home, for example over SSH.
43 + const startServer = Effect.scoped(acquireServerOwnership(serverRuntimeStatePath)).pipe(
44 + Effect.result,
45 + Effect.map((result) =>
46 + calls.push(result._tag === "Success" ? "server started" : result.failure._tag),
47 + ),
48 + Effect.provide(services),
49 + );
50 const doctor = (dryRun: boolean) =>
18 - runDoctor("/test/statev2.sqlite", { fix: true, dryRun, interactive: false }).pipe(
51 + runDoctor(
52 + { dbPath: path.join(stateDir, "statev2.sqlite"), serverRuntimeStatePath },
53 + { fix: true, dryRun, interactive: false },
54 + ).pipe(
55 Effect.provide(
56 Layer.mergeAll(
21 - NodeServices.layer,
57 Layer.mock(BootService.BootService)({
58 withStopped: (operation) =>
59 Effect.sync(() => calls.push("pause")).pipe(
@@ -35,15 +70,17 @@ it.effect(
70 legacyDatabaseBytes: 4000,
71 }),
72 compact: () =>
38 - Effect.sync(() => {
39 - calls.push("compact");
40 - return {
41 - beforeBytes: 2000,
42 - afterBytes: 1000,
43 - deletedEventCount: 1,
44 - deletedReceiptCount: 0,
45 - };
46 - }),
73 + startServer.pipe(
74 + Effect.map(() => {
75 + calls.push("compact");
76 + return {
77 + beforeBytes: 2000,
78 + afterBytes: 1000,
79 + deletedEventCount: 1,
80 + deletedReceiptCount: 0,
81 + };
82 + }),
83 + ),
84 removeLegacyDatabase: () => Effect.sync(() => calls.push("remove legacy")),
85 }),
86 ),
@@ -52,8 +89,32 @@ it.effect(
89 yield* doctor(true);
90 assert.deepEqual(calls, []);
91 yield* doctor(false);
55 - assert.deepEqual(calls, ["pause", "compact", "resume"]);
56 - }),
92 + yield* startServer;
93 + assert.deepEqual(calls, [
94 + "pause",
95 + "ServerAlreadyRunningError",
96 + "compact",
97 + "resume",
98 + "server started",
99 + ]);
100 +
101 + calls.length = 0;
102 + const state = yield* makePersistedServerRuntimeState({
103 + config: { host: undefined, devUrl: undefined },
104 + port: 3773,
105 + });
106 + const refused = yield* Effect.scoped(
107 + acquireServerOwnership(serverRuntimeStatePath).pipe(
108 + Effect.tap((owner) => owner.publish(state)),
109 + Effect.andThen(doctor(false)),
110 + ),
111 + ).pipe(Effect.flip);
112 + assert.equal(
113 + refused.message,
114 + `Stop T3 Code server process ${state.pid}, which the background service did not start, before repairing the database.`,
115 + );
116 + assert.deepEqual(calls, ["pause", "resume"]);
117 + }).pipe(Effect.provide(layerHost)),
118 );
119
120 it.effect("warns how long reclaiming can take and reports each step with its elapsed time", () =>
@@ -65,10 +126,17 @@ it.effect("warns how long reclaiming can take and reports each step with its ela
126 ["rebuild-search", "1 second"],
127 ["checkpoint", "1 second"],
128 ] as const;
68 - yield* runDoctor("/test/statev2.sqlite", { fix: true, dryRun: false, interactive: false }).pipe(
129 + const stateDir = yield* (yield* FileSystem.FileSystem).makeTempDirectoryScoped();
130 + const path = yield* Path.Path;
131 + yield* runDoctor(
132 + {
133 + dbPath: path.join(stateDir, "statev2.sqlite"),
134 + serverRuntimeStatePath: path.join(stateDir, "server-runtime.json"),
135 + },
136 + { fix: true, dryRun: false, interactive: false },
137 + ).pipe(
138 Effect.provide(
139 Layer.mergeAll(
71 - NodeServices.layer,
140 Layer.mock(BootService.BootService)({
141 withStopped: (operation) =>
142 Effect.sync(() => output.push("<pause>")).pipe(
@@ -125,5 +193,5 @@ it.effect("warns how long reclaiming can take and reports each step with its ela
193 ["0:00", "1:05", "12:46", "12:47"],
194 "each compaction step must print one line with the elapsed time as it starts",
195 );
128 - }),
196 + }).pipe(Effect.provide(layerHost)),
197 );
apps/server/src/cli/doctor.ts
+41 -11
@@ -3,10 +3,13 @@ import * as Clock from "effect/Clock";
3 import * as Console from "effect/Console";
4 import * as Effect from "effect/Effect";
5 import * as Layer from "effect/Layer";
6 +import * as Option from "effect/Option";
7 import { Command, Flag, GlobalFlag, Prompt } from "effect/cli";
8
9 import * as BootService from "../cloud/bootService.ts";
10 import * as DatabaseMaintenance from "../persistence/DatabaseMaintenance.ts";
11 +import * as ServerOwnership from "../serverOwnership.ts";
12 +import { isProcessAlive, readPersistedServerRuntimeState } from "../serverRuntimeState.ts";
13 import { projectLocationFlags, resolveCliAuthConfig } from "./config.ts";
14 import * as CliService from "./service.ts";
15
@@ -29,10 +32,37 @@ const COMPACT_STEP_LABELS: Record<DatabaseMaintenance.DatabaseCompactStep, strin
32 checkpoint: "Flushing the write-ahead log",
33 };
34
35 +// Holding the server lock refuses a server launched mid-repair, such as one started over SSH.
36 +// Lock only: acquireServerOwnership would also refuse the older service doctor just stopped.
37 +const lockServerHome = Effect.fn("runDoctor.lockServerHome")(function* (paths: {
38 + readonly dbPath: string;
39 + readonly serverRuntimeStatePath: string;
40 +}) {
41 + yield* ServerOwnership.holdServerOwnershipLock(paths.serverRuntimeStatePath).pipe(
42 + Effect.catchTags({
43 + ServerAlreadyRunningError: Effect.fn("runDoctor.nameServerHolder")(function* (cause) {
44 + const owner = yield* readPersistedServerRuntimeState(paths.serverRuntimeStatePath).pipe(
45 + Effect.map(Option.filter((state) => isProcessAlive(state.pid))),
46 + Effect.orElseSucceed(() => Option.none()),
47 + );
48 + return yield* new DatabaseMaintenance.DatabaseInUseError({
49 + path: paths.dbPath,
50 + cause,
51 + ...(Option.isSome(owner) && {
52 + pid: owner.value.pid,
53 + serviceManaged: owner.value.serviceManaged === true,
54 + }),
55 + });
56 + }),
57 + }),
58 + );
59 +});
60 +
61 export const runDoctor = Effect.fn("runDoctor")(function* (
33 - databasePath: string,
62 + paths: { readonly dbPath: string; readonly serverRuntimeStatePath: string },
63 options: { readonly fix: boolean; readonly dryRun: boolean; readonly interactive?: boolean },
64 ) {
65 + const databasePath = paths.dbPath;
66 const maintenance = yield* DatabaseMaintenance.DatabaseMaintenance;
67 const status = yield* maintenance.inspect(databasePath);
68 yield* Console.log(
@@ -123,19 +153,19 @@ export const runDoctor = Effect.fn("runDoctor")(function* (
153 );
154 // Report the repair before restarting, which can fail independently.
155 yield* service.withStopped(
126 - maintenance
127 - .compact(databasePath, reportStep)
128 - .pipe(
129 - Effect.tap((result) =>
130 - Clock.monotonicTimeNanos.pipe(
131 - Effect.flatMap((now) =>
132 - Console.log(
133 - `Done in ${formatElapsed(now - startedAt)}: ${formatBytes(result.beforeBytes)} -> ${formatBytes(result.afterBytes)}, ${result.deletedEventCount} superseded events removed.`,
134 - ),
156 + lockServerHome(paths).pipe(
157 + Effect.andThen(maintenance.compact(databasePath, reportStep)),
158 + Effect.tap((result) =>
159 + Clock.monotonicTimeNanos.pipe(
160 + Effect.flatMap((now) =>
161 + Console.log(
162 + `Done in ${formatElapsed(now - startedAt)}: ${formatBytes(result.beforeBytes)} -> ${formatBytes(result.afterBytes)}, ${result.deletedEventCount} superseded events removed.`,
163 ),
164 ),
165 ),
166 ),
167 + Effect.scoped,
168 + ),
169 );
170 }
171 if (selected.includes("legacy")) {
@@ -163,7 +193,7 @@ export const doctorCommand = Command.make("doctor", {
193 Effect.gen(function* () {
194 const logLevel = yield* GlobalFlag.LogLevel;
195 const config = yield* resolveCliAuthConfig(flags, logLevel);
166 - yield* runDoctor(config.dbPath, { fix: flags.fix, dryRun: flags.dryRun }).pipe(
196 + yield* runDoctor(config, { fix: flags.fix, dryRun: flags.dryRun }).pipe(
197 Effect.provide(Layer.merge(DatabaseMaintenance.layer, CliService.layer(config))),
198 );
199 }),
apps/server/src/persistence/DatabaseMaintenance.ts
+9 -1
@@ -28,9 +28,17 @@ export class DatabaseMissingError extends Schema.TaggedError<DatabaseMissingErro
28
29 export class DatabaseInUseError extends Schema.TaggedError<DatabaseInUseError>()(
30 "DatabaseInUseError",
31 - { path: Schema.String, cause: Schema.Defect() },
31 + {
32 + path: Schema.String,
33 + cause: Schema.Defect(),
34 + pid: Schema.optional(Schema.Int),
35 + serviceManaged: Schema.optional(Schema.Boolean),
36 + },
37 ) {
38 override get message() {
39 + if (this.pid !== undefined) {
40 + return `Stop T3 Code server process ${this.pid}${this.serviceManaged ? "" : ", which the background service did not start,"} before repairing the database.`;
41 + }
42 return "Stop the T3 Code server and desktop app, including any version before 0.1.0, before repairing the database.";
43 }
44 }
docs/user/background-service.md
+5 -2
@@ -182,8 +182,11 @@ pass `--fix` to run the recommended ones without a prompt (for scripts), or
182 `--dry-run` to only report. An installed background service for the same data
183 directory is stopped for the repair and started again afterwards, also when
184 the repair fails. Quit a server you started by hand, or the desktop app, first:
185 -the repair refuses to touch a database that is in use. Use `--base-dir` for a
186 -different data directory.
185 +the repair refuses to touch a database that is in use, and names the server
186 +process that holds it when it can tell. While the repair runs, a server started
187 +for the same data directory, for example by a desktop app connecting over SSH,
188 +is refused until the repair ends. Use `--base-dir` for a different data
189 +directory.
190
191 The repair's time grows with the size of the whole database, not only the
192 space it reclaims, and can exceed an hour on a large database or a slow disk;