The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 16:00 UTC
fix(server): storage cleanup prunes idle No project folders under ~/.t3/scratch (#36369)
Julius Marminge committed
Nov 13, 2026 at 13:21 UTC
0b5f35cd65b5f50461a2c50ee41f6945388e553c
6 files changed
+384
-116
apps/server/src/orchestration-v2/ProviderTurnStartService.test.ts
+51
@@ -320,6 +320,57 @@ effectIt.effect("restores a missing worktree before a send only under the worksp
320
}).pipe(Effect.provide(layerRestoreLeaseTest)),
321
);
322
323
+it.each([
324
+ { label: "directly in the scratch root", folder: "/tmp/t3-home/scratch/notes", recreated: true },
325
+ { label: "below another folder", folder: "/tmp/t3-home/scratch/notes/deep", recreated: false },
326
+ {
327
+ label: "in another project",
328
+ folder: "/tmp/elsewhere/notes",
329
+ workspaceRoot: "/tmp/elsewhere",
330
+ recreated: false,
331
+ },
332
+])("recreates a pruned No project folder only $label", async (input) => {
333
+ const makeDirectory = vi.fn(() => Effect.void);
334
+ await Effect.gen(function* () {
335
+ const { restore } = yield* ThreadWorktreeRestore;
336
+ yield* restore({
337
+ id: ThreadId.make("thread_scratch_restore"),
338
+ projectId: ProjectId.make("project_scratch_restore"),
339
+ worktreePath: input.folder,
340
+ branch: null,
341
+ });
342
+ }).pipe(
343
+ Effect.provide(
344
+ layerThreadWorktreeRestore.pipe(
345
+ Layer.provide(
346
+ Layer.mergeAll(
347
+ Layer.succeed(FileSystem.FileSystem, {
348
+ exists: () => Effect.succeed(false),
349
+ realPath: (target: string) => Effect.succeed(target),
350
+ makeDirectory,
351
+ } as never),
352
+ Path.layer,
353
+ Layer.mock(ServerConfig.ServerConfig)({
354
+ baseDir: "/tmp/t3-home",
355
+ worktreesDir: managedWorktreesDir,
356
+ } as ServerConfig.ServerConfig["Service"]),
357
+ ServerSettings.layerTest(),
358
+ Layer.mock(GitWorkflow.GitWorkflowService)({}),
359
+ Layer.mock(ProjectService.ProjectService)({
360
+ getById: () =>
361
+ Effect.succeedSome({
362
+ workspaceRoot: input.workspaceRoot ?? "/tmp/t3-home/scratch",
363
+ } as never),
364
+ }),
365
+ ),
366
+ ),
367
+ ),
368
+ ),
369
+ Effect.runPromise,
370
+ );
371
+ expect(makeDirectory).toHaveBeenCalledTimes(input.recreated ? 1 : 0);
372
+});
373
+
374
function makeLocalCommandHarness(input: {
375
readonly text: string;
376
readonly nativeGoals?: boolean;
apps/server/src/project/ManagedProjectFolders.ts
+5
-1
@@ -66,6 +66,10 @@ export class ScratchProjectError extends Schema.TaggedError<ScratchProjectError>
66
}
67
}
68
69
+/** Where No project threads keep their folders, whether or not this T3 home allows them. */
70
+export const scratchFolderRoot = (baseDir: string, path: Path.Path) =>
71
+ path.resolve(baseDir, "scratch");
72
+
73
export type ScratchError = ScratchUnavailableError | ScratchFolderError | ScratchProjectError;
74
75
// The spawner checks cwd before spawning, so NotFound from spawn itself means a missing executable.
@@ -255,7 +259,7 @@ const make = Effect.gen(function* () {
259
Effect.flatMap(
260
(repositoryRoot): Effect.Effect<Result.Result<string, ScratchUnavailableError>> => {
261
if (repositoryRoot === null) {
258
- return Effect.succeed(Result.succeed(path.resolve(config.baseDir, "scratch")));
262
+ return Effect.succeed(Result.succeed(scratchFolderRoot(config.baseDir, path)));
263
}
264
const unavailable = new ScratchUnavailableError({
265
baseDir: config.baseDir,
apps/server/src/storageCleanup.test.ts
+97
-1
@@ -357,6 +357,7 @@ const cleanupFixture = (
357
let sessionLiveChecks = 0;
358
let onLiveCheck: Effect.Effect<void> = Effect.void;
359
let outboxStatus: string | null = null;
360
+ let scheduledThreadIds: string[] = [];
361
let fullStatusCalls = 0;
362
let gitInspections = 0;
363
let snapshotReads = 0;
@@ -467,7 +468,9 @@ const cleanupFixture = (
468
...threads.flatMap((thread) => thread.worktreePath ?? []),
469
...storedWorktreePaths,
470
].map((worktreePath) => ({ worktreePath }))
470
- : [],
471
+ : strings.join("").includes("scheduled_tasks")
472
+ ? scheduledThreadIds.map((threadId) => ({ threadId }))
473
+ : [],
474
)) as unknown as SqlClient.SqlClient),
475
Effect.provideService(GitManager.GitManager, {
476
invalidateStatus: () => Effect.void,
@@ -533,6 +536,9 @@ const cleanupFixture = (
536
setOutboxStatus: (status: string | null) => {
537
outboxStatus = status;
538
},
539
+ setScheduledThreadIds: (next: string[]) => {
540
+ scheduledThreadIds = next;
541
+ },
542
setDeletedThreads: (next: OrchestrationV2ThreadShell[]) => {
543
deletedThreads = next;
544
},
@@ -2332,6 +2338,96 @@ describe("storage cleanup reports and local file policies", () => {
2338
}),
2339
),
2340
);
2341
+ it.effect("removes an idle No project thread's scratch folder past the retention", () =>
2342
+ runCleanupTest(
2343
+ Effect.gen(function* () {
2344
+ yield* TestClock.setTime(NOW_MS);
2345
+ const fixture = yield* cleanupFixture();
2346
+ const scratchRoot = `${fixture.config.baseDir}/scratch`;
2347
+ const folder = `${scratchRoot}/quiet-otter`;
2348
+ yield* fixture.fs.makeDirectory(folder, { recursive: true });
2349
+ yield* fixture.fs.writeFileString(`${folder}/notes.md`, "scratch\n");
2350
+ fixture.setProjectRoots([scratchRoot]);
2351
+ fixture.setStoredWorktreePaths([]);
2352
+ // Only this rule lets cleanup delete untracked files, which is all a scratch folder has.
2353
+ fixture.setPolicy("tracked-changes");
2354
+ fixture.setThreads([
2355
+ shell({ worktreePath: folder, settledAt: at(-20 * DAY_MS), status: "completed" }),
2356
+ ]);
2357
+ const report = yield* fixture.service.runNow;
2358
+ expect(report.entries).toEqual([
2359
+ expect.objectContaining({ path: folder, outcome: "removed" }),
2360
+ ]);
2361
+ expect(yield* fixture.fs.exists(folder)).toBe(false);
2362
+ }),
2363
+ ),
2364
+ );
2365
+ it.effect.each([
2366
+ {
2367
+ name: "a Git repository in a subfolder",
2368
+ policy: "tracked-changes",
2369
+ repository: "clone/.git",
2370
+ reason: "Contains a nested Git repository",
2371
+ },
2372
+ {
2373
+ name: "a Git repository of its own",
2374
+ policy: "tracked-changes",
2375
+ repository: ".git",
2376
+ reason: "Contains a nested Git repository",
2377
+ },
2378
+ { name: "files under the default keep rule", reason: "Has local files (notes.md)" },
2379
+ {
2380
+ name: "a scheduled task",
2381
+ policy: "tracked-changes",
2382
+ scheduled: true,
2383
+ reason: "Thread has a scheduled task",
2384
+ },
2385
+ ] as const)(
2386
+ "keeps an idle No project thread's scratch folder with $name",
2387
+ ({
2388
+ policy,
2389
+ repository,
2390
+ scheduled,
2391
+ reason,
2392
+ }: {
2393
+ readonly policy?: WorktreeKeepWhen;
2394
+ readonly repository?: string;
2395
+ readonly scheduled?: boolean;
2396
+ readonly reason: string;
2397
+ }) =>
2398
+ runCleanupTest(
2399
+ Effect.gen(function* () {
2400
+ yield* TestClock.setTime(NOW_MS);
2401
+ const fixture = yield* cleanupFixture();
2402
+ const scratchRoot = `${fixture.config.baseDir}/scratch`;
2403
+ const folder = `${scratchRoot}/quiet-otter`;
2404
+ yield* fixture.fs.makeDirectory(
2405
+ repository === undefined ? folder : `${folder}/${repository}`,
2406
+ { recursive: true },
2407
+ );
2408
+ yield* fixture.fs.writeFileString(`${folder}/notes.md`, "scratch\n");
2409
+ // No thread owns this one, so it is listed and never removed.
2410
+ const leftover = `${scratchRoot}/leftover`;
2411
+ yield* fixture.fs.makeDirectory(leftover);
2412
+ yield* fixture.fs.utimes(leftover, 1, 1);
2413
+ fixture.setProjectRoots([scratchRoot]);
2414
+ fixture.setStoredWorktreePaths([]);
2415
+ if (policy !== undefined) fixture.setPolicy(policy);
2416
+ if (scheduled) fixture.setScheduledThreadIds(["thread-1"]);
2417
+ fixture.setThreads([
2418
+ shell({ worktreePath: folder, settledAt: at(-20 * DAY_MS), status: "completed" }),
2419
+ ]);
2420
+ const report = yield* fixture.service.runNow;
2421
+ expect(
2422
+ report.entries.map(({ path, outcome, reason }) => ({ path, outcome, reason })),
2423
+ ).toEqual([
2424
+ { path: leftover, outcome: "kept", reason: "No thread uses this folder" },
2425
+ { path: folder, outcome: "kept", reason },
2426
+ ]);
2427
+ expect(yield* fixture.fs.exists(`${folder}/notes.md`)).toBe(true);
2428
+ }),
2429
+ ),
2430
+ );
2431
it.effect("keeps a thread's worktree folder that lost its .git link", () =>
2432
runCleanupTest(
2433
Effect.gen(function* () {
apps/server/src/storageCleanup.ts
+196
-113
@@ -41,6 +41,7 @@ import { parse as parseYaml } from "yaml";
41
import * as ServerConfig from "./config.ts";
42
import * as GitManager from "./git/GitManager.ts";
43
import * as ProjectStore from "./orchestration-v2/ProjectStore.ts";
44
+import { scratchFolderRoot } from "./project/ManagedProjectFolders.ts";
45
import * as Orchestrator from "./orchestration-v2/Orchestrator.ts";
46
import * as ProjectionStore from "./orchestration-v2/ProjectionStore.ts";
47
import * as ProviderSessionManager from "./orchestration-v2/ProviderSessionManager.ts";
@@ -376,13 +377,14 @@ const make = Effect.gen(function* () {
377
);
378
379
const measureWorktree = Effect.fn("storageCleanup.measureWorktree")(
379
- function* (worktreePath: string, inspectRepositories = false) {
380
+ function* (worktreePath: string, inspectRepositories: boolean | "plain-folder" = false) {
381
const root = yield* fs.realPath(worktreePath);
382
const skipped = yield* sharedPnpmVirtualStore(root);
383
const incomplete = { bytes: null, reason: "worktree could not be fully inspected" };
383
- const repositories = new Set([pathKey(root)]);
384
+ // A plain folder is not a checkout, so a repository at its root counts like one below it.
385
+ const repositories = new Set(inspectRepositories === "plain-folder" ? [] : [pathKey(root)]);
386
const moduleStores: string[] = [];
385
- if (inspectRepositories && (yield* fs.exists(path.join(root, ".gitmodules")))) {
387
+ if (inspectRepositories === true && (yield* fs.exists(path.join(root, ".gitmodules")))) {
388
const submodules = yield* git.execute({
389
operation: "StorageCleanup.nestedRepositories",
390
cwd: root,
@@ -509,6 +511,7 @@ const make = Effect.gen(function* () {
511
roots: ReadonlyArray<string>,
512
projects: ReadonlyArray<{ readonly workspaceRoot: string }>,
513
entries: StorageCleanupReportEntry[],
514
+ scratchRoot: string | null,
515
) {
516
const rows = yield* sql<{ worktreePath: string }>`
517
SELECT DISTINCT json_extract(payload_json, '$.worktreePath') AS "worktreePath"
@@ -547,12 +550,14 @@ const make = Effect.gen(function* () {
550
(root) =>
551
!inside(root, managedRoot) && (pathKey(root) === pathKey(target) || inside(root, target)),
552
);
550
- const directories = Effect.fnUntraced(function* (parent: string, managedRoot: string) {
551
- if (inProject(parent, managedRoot)) return [];
553
+ // The scratch root is itself a project, so its folders skip the project check.
554
+ const directories = Effect.fnUntraced(function* (parent: string, managedRoot: string | null) {
555
+ const skipped = (target: string) => managedRoot !== null && inProject(target, managedRoot);
556
+ if (skipped(parent)) return [];
557
const result: string[] = [];
558
for (const name of yield* fs.readDirectory(parent).pipe(Effect.orElseSucceed(() => []))) {
559
const target = path.join(parent, name);
555
- if (!inside(parent, target) || inProject(target, managedRoot)) continue;
560
+ if (!inside(parent, target) || skipped(target)) continue;
561
const directory = yield* Effect.gen(function* () {
562
if (pathKey(yield* fs.realPath(target)) !== pathKey(target)) return false;
563
return (yield* fs.stat(target)).type === "Directory";
@@ -567,7 +572,7 @@ const make = Effect.gen(function* () {
572
let firstMeasurement = true;
573
const reported = new Set<string>();
574
const report = Effect.fnUntraced(
570
- function* (worktreePath: string) {
575
+ function* (worktreePath: string, scratch = false) {
576
const key = pathKey(worktreePath);
577
if (
578
reported.has(key) ||
@@ -595,7 +600,9 @@ const make = Effect.gen(function* () {
600
outcome: "kept",
601
reason: linked
602
? "No thread uses this worktree"
598
- : "No thread uses this folder, and it isn't a git worktree",
603
+ : scratch
604
+ ? "No thread uses this folder"
605
+ : "No thread uses this folder, and it isn't a git worktree",
606
path: worktreePath,
607
projectPath: null,
608
threadId: null,
@@ -643,6 +650,8 @@ const make = Effect.gen(function* () {
650
}).pipe(Effect.orElseSucceed(() => undefined));
651
}
652
}
653
+ if (scratchRoot !== null)
654
+ for (const folder of yield* directories(scratchRoot, null)) yield* report(folder, true);
655
for (const key of orphanSizes.keys()) {
656
if (!reported.has(key)) orphanSizes.delete(key);
657
}
@@ -1000,6 +1009,32 @@ const make = Effect.gen(function* () {
1009
);
1010
if (root !== null && !isFilesystemRoot(root, path)) roots.push(root);
1011
}
1012
+ const scratchRoot = yield* fs
1013
+ .realPath(scratchFolderRoot(config.baseDir, path))
1014
+ .pipe(Effect.orElseSucceed(() => null));
1015
+ // Nothing can bring a scratch folder's files back, so these hold whatever the retention says.
1016
+ const scratchKeepReason = Effect.fn("StorageCleanup.scratchKeepReason")(function* (
1017
+ folder: string,
1018
+ threadIds: ReadonlyArray<string>,
1019
+ rules: WorktreeCleanupRules,
1020
+ ) {
1021
+ const realParent = yield* fs.realPath(path.dirname(folder));
1022
+ if ((yield* fs.realPath(folder)) !== path.join(realParent, path.basename(folder)))
1023
+ return "folder is a symbolic link";
1024
+ // Every file here is untracked, and only "tracked-changes" lets cleanup delete those.
1025
+ if (rules.worktreeKeepWhen !== "tracked-changes") {
1026
+ const file = (yield* fs.readDirectory(folder)).find((name) => name !== "node_modules");
1027
+ if (file !== undefined) return `has local files (${file})`;
1028
+ }
1029
+ // Each run of a scheduled task works on what its earlier runs left in the folder.
1030
+ const scheduled = yield* sql<{ threadId: string }>`
1031
+ SELECT thread_id AS "threadId" FROM scheduled_tasks
1032
+ WHERE enabled = 1 AND thread_id IS NOT NULL
1033
+ `.pipe(NodeSqliteClient.readOnly);
1034
+ if (scheduled.some((task) => threadIds.includes(task.threadId)))
1035
+ return "thread has a scheduled task";
1036
+ return null;
1037
+ });
1038
const worktreePathReason = Effect.fn("StorageCleanup.worktreePathReason")(function* (
1039
worktreePath: string,
1040
) {
@@ -1100,6 +1135,11 @@ const make = Effect.gen(function* () {
1135
const worktreeKey = yield* canonical(worktreePath);
1136
const worktreePaths = [worktreePath, worktreeKey];
1137
const group = groups.get(worktreeKey) ?? [];
1138
+ // No project threads have no branch; their folders sit directly in the scratch root.
1139
+ const scratch =
1140
+ thread.branch === null &&
1141
+ scratchRoot !== null &&
1142
+ pathKey(path.dirname(worktreeKey)) === pathKey(scratchRoot);
1143
const activityAt = Math.max(...group.map(storageCleanupActivityAt));
1144
const deleted = "workspaceRoot" in thread;
1145
const settlementChain = deleted
@@ -1147,7 +1187,7 @@ const make = Effect.gen(function* () {
1187
return keep(`shared by ${members.length} threads`);
1188
if (project === undefined) return keep("project is unavailable");
1189
if (
1150
- thread.branch === null ||
1190
+ (thread.branch === null && !scratch) ||
1191
!group.every((member) => storageCleanupThreadIdle(member, now, serverSettings))
1192
)
1193
return keep(waitForStop("thread is running or has pending work"));
@@ -1199,8 +1239,153 @@ const make = Effect.gen(function* () {
1239
: settings.worktreeUnchanged
1240
? "not settled"
1241
: "no rules apply";
1242
+ // The merge and unchanged rules read Git, which a scratch folder does not have.
1243
+ if (scratch && !eligible)
1244
+ return keep(
1245
+ settings.worktreeAfterDays !== null || settings.worktreeSettledAfterDays !== null
1246
+ ? notDueReason
1247
+ : "no rules apply",
1248
+ );
1249
// Only Git-based rules can make a not-yet-due worktree eligible, so skip Git otherwise.
1250
if (!eligible && !unchangedApplies && !settings.worktreeOnMerge) return keep(notDueReason);
1251
+ // Re-read this path's threads and sessions so new activity cancels removal; full per-worktree snapshots take seconds.
1252
+ const blockedSinceCheck = Effect.fnUntraced(function* () {
1253
+ const latestProjects = yield* projectStore.listShells();
1254
+ if (yield* containsProjectRoot(worktreePaths, [project, ...latestProjects]))
1255
+ return "contains a project checkout";
1256
+ const bindings = yield* projections.getThreadWorktreePaths({ includeArchived: true });
1257
+ const bindingKeys = yield* Effect.forEach(bindings, (binding) =>
1258
+ canonical(binding.worktreePath),
1259
+ );
1260
+ const latest = bindings.filter((_binding, index) => bindingKeys[index] === worktreeKey);
1261
+ if (yield* hasTerminal(worktreePaths)) return waitForStop("open terminal");
1262
+ if (deleted) {
1263
+ if (
1264
+ !resolveWorktreeCleanup(yield* settingsService.getSettings, thread.projectId)
1265
+ .worktreeOnDelete
1266
+ )
1267
+ return "thread or cleanup settings changed since check";
1268
+ // Durable deletion cleanup must succeed or be explicitly cancelled before removing its checkout.
1269
+ const pendingCleanup = yield* sql<{ status: string }>`
1270
+ SELECT status FROM orchestration_v2_effect_outbox
1271
+ WHERE thread_id = ${thread.id} AND status NOT IN ('succeeded', 'cancelled')
1272
+ `.pipe(NodeSqliteClient.readOnly);
1273
+ // Failed effects never retry, so only running work can finish and free the path.
1274
+ if (pendingCleanup.some((row) => row.status !== "failed"))
1275
+ return waitForStop("thread deletion is still pending");
1276
+ if (pendingCleanup.length > 0) return "thread deletion is still pending";
1277
+ }
1278
+ const latestShells = yield* Effect.forEach(latest, (entry) =>
1279
+ projections.getThreadShell(entry.threadId),
1280
+ );
1281
+ const latestGroup = latestShells.filter((shell) => shell !== null);
1282
+ const latestKeys = yield* Effect.forEach(latestGroup, (shell) =>
1283
+ shell.worktreePath === null ? Effect.succeed(null) : canonical(shell.worktreePath),
1284
+ );
1285
+ const latestOwner = worktreeOwner(deleted ? [thread, ...latestGroup] : latestGroup);
1286
+ if (
1287
+ latestGroup.length !== group.length ||
1288
+ latestOwner?.id !== thread.id ||
1289
+ latestOwner?.branch !== thread.branch ||
1290
+ latestGroup.some((shell, index) => {
1291
+ const previous = group.find((member) => member.id === shell.id);
1292
+ return (
1293
+ previous === undefined ||
1294
+ shell.branch !== thread.branch ||
1295
+ !Equal.equals(shell.settledAt, previous.settledAt) ||
1296
+ (shell.settledAt !== null && !Equal.equals(shell.updatedAt, previous.updatedAt)) ||
1297
+ !storageCleanupThreadIdle(shell, now, serverSettings) ||
1298
+ latestKeys[index] !== worktreeKey ||
1299
+ storageCleanupActivityAt(shell) !== storageCleanupActivityAt(previous)
1300
+ );
1301
+ })
1302
+ )
1303
+ return waitForStop("thread activity or shared worktree changed since check");
1304
+ if (settlementChain.length > 1) {
1305
+ const ancestors = yield* Effect.forEach(settlementChain.slice(1), (ancestor) =>
1306
+ projections.getThreadShell(ancestor.id),
1307
+ );
1308
+ const latestSettlement = worktreeSettlementChain(
1309
+ latestGroup.find((shell) => shell.id === thread.id)!,
1310
+ new Map(
1311
+ [...latestGroup, ...ancestors.filter((ancestor) => ancestor !== null)].map(
1312
+ (ancestor) => [ancestor.id, ancestor],
1313
+ ),
1314
+ ),
1315
+ now,
1316
+ serverSettings,
1317
+ ).at(-1);
1318
+ if (
1319
+ latestSettlement?.id !== settledThread?.id ||
1320
+ !Equal.equals(latestSettlement?.settledAt, settledThread?.settledAt) ||
1321
+ !Equal.equals(latestSettlement?.updatedAt, settledThread?.updatedAt)
1322
+ )
1323
+ return "parent settlement changed since check";
1324
+ }
1325
+ // Sessions can outlive their run and can be shared across app threads.
1326
+ const sessionRows = yield* sql<{ payload_json: string }>`
1327
+ SELECT payload_json FROM orchestration_v2_projection_provider_sessions
1328
+ WHERE status != 'stopped'
1329
+ `.pipe(NodeSqliteClient.readOnly);
1330
+ const sessions = yield* Effect.forEach(sessionRows, (row) =>
1331
+ decodeCleanupSession(row.payload_json),
1332
+ );
1333
+ // Ready persisted sessions may have released their runtime; only live sessions protect the path.
1334
+ for (const session of sessions) {
1335
+ if (
1336
+ (yield* occupies(worktreePaths, session.cwd)) &&
1337
+ (yield* providerSessions.isLive(session.id))
1338
+ )
1339
+ return waitForStop("provider session is still open");
1340
+ }
1341
+ return null;
1342
+ });
1343
+ const settingsChangedSinceCheck = Effect.gen(function* () {
1344
+ const currentSettings = yield* settingsService.getSettings;
1345
+ const current = resolveWorktreeCleanup(currentSettings, thread.projectId);
1346
+ return (
1347
+ currentSettings.autoResumeLimitedThreads !== serverSettings.autoResumeLimitedThreads ||
1348
+ currentSettings.snoozeLimitedThreads !== serverSettings.snoozeLimitedThreads ||
1349
+ Object.keys(settings).some(
1350
+ (key) =>
1351
+ current[key as keyof typeof settings] !== settings[key as keyof typeof settings],
1352
+ )
1353
+ );
1354
+ });
1355
+ if (scratch) {
1356
+ const threadIds = group.map((member) => member.id);
1357
+ const blocked =
1358
+ (yield* scratchKeepReason(worktreePath, threadIds, settings)) ??
1359
+ (yield* blockedSinceCheck());
1360
+ if (blocked !== null) return keep(blocked);
1361
+ const inspection = yield* measureWorktree(worktreePath, "plain-folder");
1362
+ if (inspection.reason !== null) return keep(inspection.reason);
1363
+ return yield* withWorkspaceLease(
1364
+ worktreePath,
1365
+ Effect.gen(function* () {
1366
+ // Walked again under the lease: a repository deleted with the folder is gone for good.
1367
+ const finalInspection = yield* measureWorktree(worktreePath, "plain-folder");
1368
+ if (finalInspection.reason !== null) return keep(finalInspection.reason);
1369
+ // The walk takes time, so the cheap checks run last, right before removal.
1370
+ const blockedWhileMeasuring =
1371
+ (yield* scratchKeepReason(worktreePath, threadIds, settings)) ??
1372
+ (yield* blockedSinceCheck());
1373
+ if (blockedWhileMeasuring !== null) return keep(blockedWhileMeasuring);
1374
+ if (yield* settingsChangedSinceCheck) return keep("settings changed since check");
1375
+ yield* fs.remove(worktreePath, { recursive: true });
1376
+ entries.push({
1377
+ ...entry,
1378
+ outcome: "removed",
1379
+ reason: sentence(removalReason),
1380
+ bytes: inspection.bytes,
1381
+ });
1382
+ // The stored path stays so the next turn recreates the folder, empty.
1383
+ yield* Effect.logInfo("storage cleanup removed scratch folder", {
1384
+ threadId: thread.id,
1385
+ });
1386
+ }),
1387
+ );
1388
+ }
1389
const pathReason = yield* worktreePathReason(worktreePath);
1390
if (pathReason !== null) return keep(pathReason);
1391
if (yield* containsProjectRoot(worktreePaths, [project, ...snapshot.projects]))
@@ -1311,98 +1496,6 @@ const make = Effect.gen(function* () {
1496
return keep(integrated ? notDueReason : "has commits beyond the project branch");
1497
}
1498
if (!eligible) return keep(notDueReason);
1314
- // Re-read this path's threads and sessions so new activity cancels removal; full per-worktree snapshots take seconds.
1315
- const blockedSinceCheck = Effect.fnUntraced(function* () {
1316
- const latestProjects = yield* projectStore.listShells();
1317
- if (yield* containsProjectRoot(worktreePaths, [project, ...latestProjects]))
1318
- return "contains a project checkout";
1319
- const bindings = yield* projections.getThreadWorktreePaths({ includeArchived: true });
1320
- const bindingKeys = yield* Effect.forEach(bindings, (binding) =>
1321
- canonical(binding.worktreePath),
1322
- );
1323
- const latest = bindings.filter((_binding, index) => bindingKeys[index] === worktreeKey);
1324
- if (yield* hasTerminal(worktreePaths)) return waitForStop("open terminal");
1325
- if (deleted) {
1326
- if (
1327
- !resolveWorktreeCleanup(yield* settingsService.getSettings, thread.projectId)
1328
- .worktreeOnDelete
1329
- )
1330
- return "thread or cleanup settings changed since check";
1331
- // Durable deletion cleanup must succeed or be explicitly cancelled before removing its checkout.
1332
- const pendingCleanup = yield* sql<{ status: string }>`
1333
- SELECT status FROM orchestration_v2_effect_outbox
1334
- WHERE thread_id = ${thread.id} AND status NOT IN ('succeeded', 'cancelled')
1335
- `.pipe(NodeSqliteClient.readOnly);
1336
- // Failed effects never retry, so only running work can finish and free the path.
1337
- if (pendingCleanup.some((row) => row.status !== "failed"))
1338
- return waitForStop("thread deletion is still pending");
1339
- if (pendingCleanup.length > 0) return "thread deletion is still pending";
1340
- }
1341
- const latestShells = yield* Effect.forEach(latest, (entry) =>
1342
- projections.getThreadShell(entry.threadId),
1343
- );
1344
- const latestGroup = latestShells.filter((shell) => shell !== null);
1345
- const latestKeys = yield* Effect.forEach(latestGroup, (shell) =>
1346
- shell.worktreePath === null ? Effect.succeed(null) : canonical(shell.worktreePath),
1347
- );
1348
- const latestOwner = worktreeOwner(deleted ? [thread, ...latestGroup] : latestGroup);
1349
- if (
1350
- latestGroup.length !== group.length ||
1351
- latestOwner?.id !== thread.id ||
1352
- latestOwner?.branch !== thread.branch ||
1353
- latestGroup.some((shell, index) => {
1354
- const previous = group.find((member) => member.id === shell.id);
1355
- return (
1356
- previous === undefined ||
1357
- shell.branch !== thread.branch ||
1358
- !Equal.equals(shell.settledAt, previous.settledAt) ||
1359
- (shell.settledAt !== null && !Equal.equals(shell.updatedAt, previous.updatedAt)) ||
1360
- !storageCleanupThreadIdle(shell, now, serverSettings) ||
1361
- latestKeys[index] !== worktreeKey ||
1362
- storageCleanupActivityAt(shell) !== storageCleanupActivityAt(previous)
1363
- );
1364
- })
1365
- )
1366
- return waitForStop("thread activity or shared worktree changed since check");
1367
- if (settlementChain.length > 1) {
1368
- const ancestors = yield* Effect.forEach(settlementChain.slice(1), (ancestor) =>
1369
- projections.getThreadShell(ancestor.id),
1370
- );
1371
- const latestSettlement = worktreeSettlementChain(
1372
- latestGroup.find((shell) => shell.id === thread.id)!,
1373
- new Map(
1374
- [...latestGroup, ...ancestors.filter((ancestor) => ancestor !== null)].map(
1375
- (ancestor) => [ancestor.id, ancestor],
1376
- ),
1377
- ),
1378
- now,
1379
- serverSettings,
1380
- ).at(-1);
1381
- if (
1382
- latestSettlement?.id !== settledThread?.id ||
1383
- !Equal.equals(latestSettlement?.settledAt, settledThread?.settledAt) ||
1384
- !Equal.equals(latestSettlement?.updatedAt, settledThread?.updatedAt)
1385
- )
1386
- return "parent settlement changed since check";
1387
- }
1388
- // Sessions can outlive their run and can be shared across app threads.
1389
- const sessionRows = yield* sql<{ payload_json: string }>`
1390
- SELECT payload_json FROM orchestration_v2_projection_provider_sessions
1391
- WHERE status != 'stopped'
1392
- `.pipe(NodeSqliteClient.readOnly);
1393
- const sessions = yield* Effect.forEach(sessionRows, (row) =>
1394
- decodeCleanupSession(row.payload_json),
1395
- );
1396
- // Ready persisted sessions may have released their runtime; only live sessions protect the path.
1397
- for (const session of sessions) {
1398
- if (
1399
- (yield* occupies(worktreePaths, session.cwd)) &&
1400
- (yield* providerSessions.isLive(session.id))
1401
- )
1402
- return waitForStop("provider session is still open");
1403
- }
1404
- return null;
1405
- });
1499
const blocked = yield* blockedSinceCheck();
1500
if (blocked !== null) return keep(blocked);
1501
// Inspect before the lease; provider startup must not wait for directory traversal.
@@ -1425,18 +1518,7 @@ const make = Effect.gen(function* () {
1518
return keep("commit changed since check");
1519
const finalChanges = yield* localChangesReason(worktreePath, settings);
1520
if (finalChanges !== null) return keep(finalChanges);
1428
- const currentSettings = yield* settingsService.getSettings;
1429
- const current = resolveWorktreeCleanup(currentSettings, thread.projectId);
1430
- if (
1431
- currentSettings.autoResumeLimitedThreads !==
1432
- serverSettings.autoResumeLimitedThreads ||
1433
- currentSettings.snoozeLimitedThreads !== serverSettings.snoozeLimitedThreads ||
1434
- Object.keys(settings).some(
1435
- (key) =>
1436
- current[key as keyof typeof settings] !== settings[key as keyof typeof settings],
1437
- )
1438
- )
1439
- return keep("settings changed since check");
1521
+ if (yield* settingsChangedSinceCheck) return keep("settings changed since check");
1522
// Clean only untracked files. Ordinary worktrees retain Git's final tracked-edit check.
1523
if (settings.worktreeKeepWhen === "tracked-changes")
1524
yield* cleanupGit(worktreePath, ["clean", "-ffdx"], "git clean");
@@ -1482,6 +1564,7 @@ const make = Effect.gen(function* () {
1564
roots,
1565
yield* projectStore.list({ includeDeleted: true }),
1566
entries,
1567
+ scratchRoot,
1568
);
1569
return { waiting, kept };
1570
});
apps/server/src/workspace/restoreMissingWorktree.ts
+26
-1
@@ -7,7 +7,9 @@ import * as Option from "effect/Option";
7
import * as Path from "effect/Path";
8
import * as Schema from "effect/Schema";
9
10
+import * as ServerConfig from "../config.ts";
11
import * as GitWorkflowService from "../git/GitWorkflowService.ts";
12
+import { scratchFolderRoot } from "../project/ManagedProjectFolders.ts";
13
import * as ProjectService from "../project/ProjectService.ts";
14
import { makeIsManagedWorktreePath } from "../worktreesDirectory.ts";
15
import { isWithinRoot } from "./KnownWorkspaces.ts";
@@ -52,6 +54,28 @@ export const makeRestoreMissingWorktree = Effect.gen(function* () {
54
const gitWorkflow = yield* GitWorkflowService.GitWorkflowService;
55
const projects = yield* ProjectService.ProjectService;
56
const isManagedWorktreePath = yield* makeIsManagedWorktreePath;
57
+ const serverConfig = yield* ServerConfig.ServerConfig;
58
+
59
+ // Storage cleanup prunes idle No project folders, which have no branch to restore from.
60
+ // An empty folder, only directly inside the No project's own root, lets the thread run again.
61
+ const recreateScratchFolder = Effect.fn("restoreMissingWorktree.recreateScratchFolder")(
62
+ function* (thread: WorktreeThread, folder: string) {
63
+ if (path.resolve(folder) !== folder || (yield* fileSystem.exists(folder))) return;
64
+ const project = Option.getOrUndefined(yield* projects.getById(thread.projectId));
65
+ if (project === undefined || path.dirname(folder) !== path.resolve(project.workspaceRoot))
66
+ return;
67
+ const root = scratchFolderRoot(serverConfig.baseDir, path);
68
+ const realRoot = yield* fileSystem.realPath(root).pipe(Effect.orElseSucceed(() => root));
69
+ if (path.dirname(folder) !== root && path.dirname(folder) !== realRoot) return;
70
+ yield* Effect.logWarning("recreating missing scratch folder", {
71
+ threadId: thread.id,
72
+ folder,
73
+ });
74
+ yield* fileSystem.makeDirectory(folder, { recursive: true });
75
+ },
76
+ // Turn start reports a folder that is still missing.
77
+ Effect.orElseSucceed(() => undefined),
78
+ );
79
80
// Only folders holding nothing but leftovers are cleared, never user files.
81
const isLeftoverFolder = (worktreePath: string) =>
@@ -143,7 +167,8 @@ export const makeRestoreMissingWorktree = Effect.gen(function* () {
167
168
return Effect.fn("restoreMissingWorktree")(function* (thread: WorktreeThread) {
169
const { worktreePath, branch } = thread;
146
- if (worktreePath === null || branch === null) return;
170
+ if (worktreePath === null) return;
171
+ if (branch === null) return yield* recreateScratchFolder(thread, worktreePath);
172
const exists = yield* fileSystem.exists(worktreePath).pipe(Effect.orElseSucceed(() => true));
173
const leftover = exists && (yield* isLeftoverFolder(worktreePath));
174
if ((exists && !leftover) || !(yield* isManagedWorktreePath(worktreePath))) return;
docs/user/project-settings.md
+9
@@ -250,6 +250,15 @@ Choose **Delete now** to run the enabled rules immediately. The latest results s
250
worktrees were removed or kept and why, plus any failures.
251
Results also list folders in the worktree folder that no thread uses, with their sizes; cleanup never removes them, so remove them manually if you want.
252
253
+The inactive and settled retention periods also apply to the folders of
254
+[threads without a project](./thread-sidebar.md#start-without-a-project). Those folders are not
255
+Git repositories, so their files are deleted with them and cannot be recovered; the thread stays,
256
+and its next turn starts in a new, empty folder. A folder is kept when it has a Git repository
257
+anywhere inside it or when its thread has an enabled scheduled task. Every file in such a folder
258
+counts as untracked, so only **Edited tracked files** removes a folder that holds anything other
259
+than `node_modules`; the other two rules remove only empty folders. Folders that no thread uses
260
+are listed here too.
261
+
262
Browser captures and rotated logs have separate retention periods. Expired capture links stop
263
working. Current logs, message attachments, and browser profiles are kept.
264