From 83609f86364358085e3ce1adb333d1604161f16e Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Wed, 18 Nov 2026 15:46:24 +0000 Subject: [PATCH 1/2] hold-work: --hold-work needs --base-dir; one marker read per boot (#439) - `t3 serve --hold-work` is refused without --base-dir, with a blank one, and on the default home (~/.t3, any spelling or a symlink to it), before anything starts or is written: a held boot marks its home, and on the live home that holds T3 Connect at every later boot. The refusals move to the fork file cli/forkHoldWork.ts, so cli/server.ts keeps 20 fewer fork lines (pending ceiling 37 -> 17, lost 4 -> 3). - The held-copy marker is read once per boot: one ConnectHoldDecision layer value, shared by the CloudLink and agent activity wrappers, so the two can never disagree. Unit test counts the reads (2 on the old code) and covers a marker deleted during boot; the boot test asserts one heldCopyMarker span per boot. - A comment says the marker check fails closed on purpose. - Docs: --base-dir rule, one shared read, and a userdata-only copy of a marked copy is not protected. Co-Authored-By: Claude Opus 5.5 --- .github/fork-seams.json | 6 +- apps/server/src/cli/forkHoldWork.ts | 67 +++++++++++++ apps/server/src/cli/server.holdWork.test.ts | 97 ++++++++++++++++++- apps/server/src/cli/server.ts | 28 +----- apps/server/src/cloud/holdWorkConnect.test.ts | 96 ++++++++++++++++++ apps/server/src/cloud/holdWorkConnect.ts | 45 ++++++--- apps/server/src/holdWork.boot.test.ts | 16 ++- docs/fork/updates.md | 19 ++-- 8 files changed, 322 insertions(+), 52 deletions(-) create mode 100644 apps/server/src/cli/forkHoldWork.ts diff --git a/.github/fork-seams.json b/.github/fork-seams.json index cf85e3508d5c6..45ff09bec6965 100644 --- a/.github/fork-seams.json +++ b/.github/fork-seams.json @@ -143,7 +143,7 @@ "apps/server/src/binCli.ts": 2, "apps/server/src/binMain.ts": 6, "apps/server/src/cli/config.ts": 2, - "apps/server/src/cli/server.ts": 37, + "apps/server/src/cli/server.ts": 17, "apps/server/src/cloud/selfUpdate.ts": 4, "apps/server/src/config.ts": 2, "apps/server/src/mcp/McpHttpServer.ts": 10, @@ -271,8 +271,8 @@ "gone": 1 }, "apps/server/src/cli/server.ts": { - "lines": 4, - "gone": 4 + "lines": 3, + "gone": 3 }, "apps/server/src/mcp/McpHttpServer.ts": { "lines": 1, diff --git a/apps/server/src/cli/forkHoldWork.ts b/apps/server/src/cli/forkHoldWork.ts new file mode 100644 index 0000000000000..d3918d5eff23f --- /dev/null +++ b/apps/server/src/cli/forkHoldWork.ts @@ -0,0 +1,67 @@ +/** + * Fork (go-live kit): the refusals `t3 serve --hold-work` runs before config resolution, which + * claims a port and creates directories. cli/server.ts calls `refuseHoldWork` once. + */ +import * as Effect from "effect/Effect"; +import * as FileSystem from "effect/FileSystem"; +import * as Option from "effect/Option"; +import * as CliError from "effect/cli/CliError"; + +import { resolveServiceLauncherMode } from "../cloud/serviceLauncherClient.ts"; +import { resolveBaseDir } from "../os-jank.ts"; + +/** The background service must never run held: its threads would silently stop working. A + * launcher context that cannot be read refuses too. */ +export const refuseHoldWorkForBootService = resolveServiceLauncherMode().pipe( + Effect.map(({ managed }) => managed), + Effect.orElseSucceed(() => true), + Effect.flatMap((managed) => + managed + ? Effect.fail( + new CliError.UserError({ + cause: "hold-work", + userMessage: + "--hold-work is refused for the background service. Run `t3 serve --hold-work --base-dir ` by hand on a copy of a T3 home.", + }), + ) + : Effect.void, + ), +); + +const defaultHomeRefusal = (detail: string) => + new CliError.UserError({ + cause: "hold-work", + userMessage: [ + `--hold-work is refused ${detail}.`, + "A held boot writes hold-work-copy.txt in its home, and every later boot of that home then holds T3 Connect (no tunnel, no agent activity) until someone deletes the file: on the live home that ends remote access.", + "Run `t3 serve --hold-work --base-dir ` on a copy of a T3 home. Nothing was started or written.", + ].join("\n"), + }); + +/** + * `--hold-work` marks the home it runs on as a copy (cloud/holdWorkConnect.ts), so it needs a home + * named with `--base-dir`, and never the default home (`~/.t3`), which is the live one on most + * machines. `T3CODE_HOME` alone does not count: it is set in a shell, not written on the command. + */ +export const refuseHoldWorkOnDefaultHome = Effect.fn("cli.refuseHoldWorkOnDefaultHome")(function* ( + baseDirFlag: Option.Option, +) { + const named = baseDirFlag.pipe(Option.filter((value) => value.trim().length > 0)); + if (Option.isNone(named)) { + return yield* defaultHomeRefusal("without --base-dir: it would run on this machine's T3 home"); + } + const home = yield* resolveBaseDir(named.value); + const defaultHome = yield* resolveBaseDir(undefined); + // A symlink to the default home is the default home: compare real paths when both exist. + const fs = yield* FileSystem.FileSystem; + const real = (path: string) => fs.realPath(path).pipe(Effect.orElseSucceed(() => path)); + if (home === defaultHome || (yield* real(home)) === (yield* real(defaultHome))) { + return yield* defaultHomeRefusal( + `on the default T3 home (${defaultHome}): it is the live one on most machines`, + ); + } +}); + +/** Every refusal of `serve --hold-work`, before anything is started or written. */ +export const refuseHoldWork = (baseDirFlag: Option.Option) => + refuseHoldWorkForBootService.pipe(Effect.andThen(refuseHoldWorkOnDefaultHome(baseDirFlag))); diff --git a/apps/server/src/cli/server.holdWork.test.ts b/apps/server/src/cli/server.holdWork.test.ts index ed9c0e92b57e1..03ac2a747c5ef 100644 --- a/apps/server/src/cli/server.holdWork.test.ts +++ b/apps/server/src/cli/server.holdWork.test.ts @@ -1,16 +1,18 @@ // @effect-diagnostics nodeBuiltinImport:off - CLI integration uses temporary Node paths. -// Fork (go-live kit): `serve --hold-work` is refused for the background service. +// Fork (go-live kit): `serve --hold-work` is refused for the background service and on the default +// home (it would mark the live home as a copy). import * as NodePath from "node:path"; import * as NodeCrypto from "@effect/platform-node/NodeCrypto"; import * as NodeServices from "@effect/platform-node/NodeServices"; -import { assert, it } from "@effect/vitest"; +import { assert, describe, expect, it } from "@effect/vitest"; import * as HostProcess from "@t3tools/shared/HostProcess"; import * as NetService from "@t3tools/shared/Net"; import * as Effect from "effect/Effect"; import * as Exit from "effect/Exit"; import * as FileSystem from "effect/FileSystem"; import * as Layer from "effect/Layer"; +import * as Option from "effect/Option"; import { Command } from "effect/cli"; import packageJson from "../../package.json" with { type: "json" }; @@ -20,7 +22,7 @@ import { SERVICE_LAUNCHER_PROTOCOL, } from "../cloud/serviceProtocol.ts"; import { cli } from "../binCli.ts"; -import { refuseHoldWorkForBootService } from "./server.ts"; +import { refuseHoldWorkForBootService, refuseHoldWorkOnDefaultHome } from "./forkHoldWork.ts"; const launcher = (input: { readonly connected: boolean; readonly context?: string }) => ({ host: { @@ -94,3 +96,92 @@ it.effect("parses serve --hold-work and refuses it under the launcher before cre assert.isFalse(yield* fs.exists(baseDir)); }).pipe(Effect.provide(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer))), ); + +describe("serve --hold-work needs a home named with --base-dir, never the default one", () => { + /** A temp folder stands in for the user's home folder, so `~/.t3` is `/.t3`. */ + const onHome = (body: (root: string) => Effect.Effect) => + Effect.gen(function* () { + const fs = yield* FileSystem.FileSystem; + const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-hold-work-home-" }); + return yield* body(root).pipe(Effect.provideService(HostProcess.HomeDirectory, root)); + }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)); + + const refusal = (flag: Option.Option) => + refuseHoldWorkOnDefaultHome(flag).pipe( + Effect.flip, + Effect.map((error) => error.message), + ); + + it.effect("refuses no --base-dir, or a blank one, and says what to run", () => + onHome(() => + Effect.gen(function* () { + for (const flag of [Option.none(), Option.some(""), Option.some(" ")]) { + const message = yield* refusal(flag); + expect(message).toContain("--hold-work is refused without --base-dir"); + expect(message).toContain("--base-dir "); + expect(message).toContain("hold-work-copy.txt"); + } + }), + ), + ); + + it.effect("refuses the default home however it is spelled, or a symlink to it", () => + onHome((root) => + Effect.gen(function* () { + const fs = yield* FileSystem.FileSystem; + const defaultHome = NodePath.join(root, ".t3"); + yield* fs.makeDirectory(defaultHome); + yield* fs.symlink(defaultHome, NodePath.join(root, "live-link")); + for (const flag of [ + defaultHome, + `${defaultHome}/`, + "~/.t3", + NodePath.join(root, "x", "..", ".t3"), + NodePath.join(root, "live-link"), + ]) { + const message = yield* refusal(Option.some(flag)); + expect(message).toContain( + `--hold-work is refused on the default T3 home (${defaultHome})`, + ); + } + }), + ), + ); + + it.effect("lets a named copy through, made or not", () => + onHome((root) => + Effect.gen(function* () { + const fs = yield* FileSystem.FileSystem; + yield* refuseHoldWorkOnDefaultHome(Option.some(NodePath.join(root, "copy", "home"))); + yield* fs.makeDirectory(NodePath.join(root, "made")); + yield* refuseHoldWorkOnDefaultHome(Option.some(NodePath.join(root, "made"))); + // Beside the default home, not the default home itself. + yield* refuseHoldWorkOnDefaultHome(Option.some("~/.t3-copy")); + }), + ), + ); + + it.effect("serve --hold-work with no --base-dir is refused before the default home is made", () => + onHome((root) => + Effect.gen(function* () { + const fs = yield* FileSystem.FileSystem; + const { host, env } = launcher({ connected: false }); + const exit = yield* Command.runWith(cli, { version: "0.0.0" })([ + "serve", + "--hold-work", + ]).pipe( + Effect.provideService(ServiceLauncherHostProcess, host), + Effect.provideService(HostProcess.Environment, env), + Effect.provide(Layer.mergeAll(NodeServices.layer, NetService.layer)), + Effect.exit, + ); + assert.isTrue(Exit.isFailure(exit)); + assert.include( + String(Exit.isFailure(exit) ? exit.cause : ""), + "--hold-work is refused without --base-dir", + ); + assert.isFalse(yield* fs.exists(NodePath.join(root, ".t3"))); + }).pipe(Effect.provide(NodeCrypto.layer)), + ), + ); +}); diff --git a/apps/server/src/cli/server.ts b/apps/server/src/cli/server.ts index 82d196160b277..1cee0799eb82a 100644 --- a/apps/server/src/cli/server.ts +++ b/apps/server/src/cli/server.ts @@ -6,15 +6,13 @@ import * as Schema from "effect/Schema"; import { Command, Flag, GlobalFlag } from "effect/cli"; import * as CliError from "effect/cli/CliError"; -import { - awaitServiceLauncherStop, - resolveServiceLauncherMode, -} from "../cloud/serviceLauncherClient.ts"; +import { awaitServiceLauncherStop } from "../cloud/serviceLauncherClient.ts"; import * as ServerConfig from "../config.ts"; import { awaitLauncherLoss } from "../launcherWatch.ts"; import * as DatabaseMaintenance from "../persistence/DatabaseMaintenance.ts"; import * as ProcessRunner from "../processRunner.ts"; import * as AutomaticPort from "./automaticPort.ts"; +import * as ForkHoldWork from "./forkHoldWork.ts"; import { type CliServerFlags, resolveServerConfig, sharedServerCommandFlags } from "./config.ts"; const encodeCommand = Schema.encodeEffect(Schema.fromJsonString(Schema.String)); @@ -28,7 +26,7 @@ const runServerCommand = Effect.fn("server.runServerCommand")(function* ( readonly holdWork?: boolean; }, ) { - if (options?.holdWork === true) yield* refuseHoldWorkForBootService; + if (options?.holdWork === true) yield* ForkHoldWork.refuseHoldWork(flags.baseDir); // Before config resolution, which claims a port and creates directories. const { runServer } = yield* Effect.promise(() => import("../server.ts")); const logLevel = yield* GlobalFlag.LogLevel; @@ -87,29 +85,11 @@ export const startCommand = Command.make("start", { ...sharedServerCommandFlags // Fork (go-live kit): a server that starts no agent work, to try a build on a copy of a T3 home. const holdWorkFlag = Flag.Boolean("hold-work").pipe( Flag.withDescription( - "Start no agent work, for trying a build on a copy of a T3 home: no turn, launch, scheduled task, wait, usage-limit resume, project pull, linked-environment follow-up, startup analytics ping or T3 Connect tunnel (a copy's stored link is kept, unused). Startup recovery and provider status checks (which start the provider CLIs, no turn) still run. Refused for the background service.", + "Start no agent work, for trying a build on a copy of a T3 home: no turn, launch, scheduled task, wait, usage-limit resume, project pull, linked-environment follow-up, startup analytics ping or T3 Connect tunnel (a copy's stored link is kept, unused). Startup recovery and provider status checks (which start the provider CLIs, no turn) still run. Needs --base-dir; refused on the default home and for the background service.", ), Flag.withDefault(false), ); -/** The background service must never run held: its threads would silently stop working. A - * launcher context that cannot be read refuses too. */ -export const refuseHoldWorkForBootService = resolveServiceLauncherMode().pipe( - Effect.map(({ managed }) => managed), - Effect.orElseSucceed(() => true), - Effect.flatMap((managed) => - managed - ? Effect.fail( - new CliError.UserError({ - cause: "hold-work", - userMessage: - "--hold-work is refused for the background service. Run `t3 serve --hold-work --base-dir ` by hand on a copy of a T3 home.", - }), - ) - : Effect.void, - ), -); - // Serve never bootstraps a project, so it does not offer the flag that asks for one. const { autoBootstrapProjectFromCwd: _, ...serveCommandFlags } = sharedServerCommandFlags; diff --git a/apps/server/src/cloud/holdWorkConnect.test.ts b/apps/server/src/cloud/holdWorkConnect.test.ts index 50f7d04338b1a..aff79fb4245da 100644 --- a/apps/server/src/cloud/holdWorkConnect.test.ts +++ b/apps/server/src/cloud/holdWorkConnect.test.ts @@ -371,3 +371,99 @@ describe("holdWorkConnect CLI refusal on a held copy's home", () => { }), ); }); + +describe("holdWorkConnect one marker read per boot", () => { + /** Both held layers built together, as one server builds them, on a FileSystem that counts marker checks. */ + const bootBoth = (baseDir: string, deleteMarkerWhileCloudLinkBuilds: boolean) => + Effect.gen(function* () { + const markerPath = `${baseDir}/${HoldWorkConnect.HELD_COPY_MARKER_FILE}`; + const checks: Array = []; + const countingFs = Layer.effect( + FileSystem.FileSystem, + Effect.gen(function* () { + const fs = yield* FileSystem.FileSystem; + return FileSystem.FileSystem.of({ + ...fs, + exists: (path) => { + if (path === markerPath) checks.push("exists"); + return fs.exists(path); + }, + }); + }), + ).pipe(Layer.provide(NodeServices.layer)); + const cloud = recordingCloudLink(); + const relayCalls: Array = []; + // A hand edit while the server starts: the marker is deleted as the real CloudLink is built. + const fakeCloudLink = Layer.effect( + CloudLink.CloudLink, + Effect.gen(function* () { + if (deleteMarkerWhileCloudLinkBuilds) { + yield* (yield* FileSystem.FileSystem).remove(markerPath); + } + return cloud.service; + }), + ); + const fakeRelay = Layer.succeed( + AgentAwarenessRelay.AgentAwarenessRelay, + AgentAwarenessRelay.AgentAwarenessRelay.of({ + publishThread: () => Effect.sync(() => void relayCalls.push("publishThread")), + drain: Effect.sync(() => void relayCalls.push("drain")), + requestCatchUp: () => Effect.sync(() => void relayCalls.push("requestCatchUp")), + start: () => Effect.sync(() => void relayCalls.push("start")), + }), + ); + const gate = yield* WorkAdmission.makeWorkAdmissionGate({ heldFromBoot: false }); + const [cloudLink, relay] = yield* Effect.all([ + Effect.service(CloudLink.CloudLink), + Effect.service(AgentAwarenessRelay.AgentAwarenessRelay), + ]).pipe( + Effect.provide( + Layer.mergeAll( + HoldWorkConnect.layer(fakeCloudLink), + HoldWorkConnect.agentActivityLayer(fakeRelay), + ).pipe( + Layer.provide(Layer.succeed(WorkAdmission.WorkAdmission, gate)), + Layer.provide(homeConfig(baseDir)), + Layer.provide(countingFs), + Layer.provide(NodeServices.layer), + ), + ), + ); + return { checks, cloud, cloudLink, relay, relayCalls }; + }); + + it.effect.each([ + { label: "a marked home", deleteMarkerWhileCloudLinkBuilds: false }, + { + label: "a marked home whose marker is deleted by hand during the boot", + deleteMarkerWhileCloudLinkBuilds: true, + }, + ])( + "CloudLink and agent activity share one read on $label, so both hold", + ({ deleteMarkerWhileCloudLinkBuilds }) => + Effect.gen(function* () { + const fs = yield* FileSystem.FileSystem; + const baseDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-hold-work-once-" }); + yield* fs.writeFileString(`${baseDir}/${HoldWorkConnect.HELD_COPY_MARKER_FILE}`, "marked"); + const boot = yield* bootBoth(baseDir, deleteMarkerWhileCloudLinkBuilds); + expect(boot.checks).toEqual(["exists"]); + expect(yield* boot.cloudLink.startManagedTunnelIfOriginConfirmed(ORIGIN)).toBe(false); + expect(yield* boot.cloudLink.releaseManagedTunnelOnShutdown()).toBe(false); + expect(boot.cloud.calls).toEqual([]); + yield* useRelay(boot.relay); + expect(boot.relayCalls).toEqual([]); + }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)), + ); + + it.effect("an unmarked home is read once too, and neither part is held", () => + Effect.gen(function* () { + const fs = yield* FileSystem.FileSystem; + const baseDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-hold-work-once-" }); + const boot = yield* bootBoth(baseDir, false); + expect(boot.checks).toEqual(["exists"]); + expect(yield* boot.cloudLink.startManagedTunnelIfOriginConfirmed(ORIGIN)).toBe("ran"); + yield* useRelay(boot.relay); + expect(boot.relayCalls).toEqual(["start", "publishThread", "requestCatchUp", "drain"]); + }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)), + ); +}); diff --git a/apps/server/src/cloud/holdWorkConnect.ts b/apps/server/src/cloud/holdWorkConnect.ts index dd6f4a6826859..e97a4e54eb470 100644 --- a/apps/server/src/cloud/holdWorkConnect.ts +++ b/apps/server/src/cloud/holdWorkConnect.ts @@ -2,6 +2,7 @@ // server's Connect environment id, so it starts, registers and releases no tunnel, publishes no // agent activity, and refuses to link, change or unlink (an unlink ends in a relay delete of that // id). Every method is listed by name, never spread: a new upstream method is a type error here. +import * as Context from "effect/Context"; import * as DateTime from "effect/DateTime"; import * as Effect from "effect/Effect"; import * as FileSystem from "effect/FileSystem"; @@ -80,14 +81,27 @@ const holdConnect = ( }); }; -/** Held from boot, or a normal boot of a home a held boot marked; read once, as the layer builds. */ -const connectHold = Effect.gen(function* () { - if ((yield* WorkAdmission.WorkAdmission).heldFromBoot) { - return Option.some({ markerPath: null }); - } - const marker = yield* heldCopyMarker((yield* ServerConfig.ServerConfig).baseDir); - return Option.map(marker, (markerPath): ConnectHold => ({ markerPath })); -}); +/** Whether this boot holds Connect: held from boot, or a normal boot of a home a held boot marked. */ +class ConnectHoldDecision extends Context.Service< + ConnectHoldDecision, + Option.Option +>()("t3/cloud/holdWorkConnect/ConnectHoldDecision") {} + +/** + * The boot's one read of the marker. `layer` and `agentActivityLayer` both provide this one layer + * value, and a server builds a layer value once, so CloudLink and agent activity share the result: + * a marker deleted or added by hand while the server starts cannot hold one and not the other. + */ +const connectHoldDecision = Layer.effect( + ConnectHoldDecision, + Effect.gen(function* () { + if ((yield* WorkAdmission.WorkAdmission).heldFromBoot) { + return Option.some({ markerPath: null }); + } + const marker = yield* heldCopyMarker((yield* ServerConfig.ServerConfig).baseDir); + return Option.map(marker, (markerPath): ConnectHold => ({ markerPath })); + }), +); /** * A held boot marks its home as a copy before the real CloudLink is built, so the CLI refusals @@ -122,7 +136,7 @@ export const layer = (cloudLinkLayer: Layer.Layer(cloudLinkLayer: Layer.Layer @@ -163,10 +181,10 @@ export const agentActivityLayer = ( AgentAwarenessRelay.AgentAwarenessRelay, Effect.gen(function* () { const relay = yield* AgentAwarenessRelay.AgentAwarenessRelay; - const hold = yield* connectHold; + const hold = yield* ConnectHoldDecision; return Option.isSome(hold) ? holdAgentActivity(hold.value) : relay; }), - ).pipe(Layer.provide(relayLayer)); + ).pipe(Layer.provide(relayLayer), Layer.provide(connectHoldDecision)); /** Written in a home by a held boot. Every boot and the `t3 connect` refusals read it; nothing removes it. */ export const HELD_COPY_MARKER_FILE = "hold-work-copy.txt"; @@ -190,6 +208,9 @@ const heldCopyMarker = Effect.fn("HoldWorkConnect.heldCopyMarker")(function* (ba ), ), ), + // Fails closed on purpose: a check that errors (EIO, EACCES) counts as marked, so a copy is + // never let reach Connect because its marker could not be read. On the live home that holds + // Connect for that boot only, and the log names the file. Do not turn this into fail-open. Effect.orElseSucceed(() => true), ); return marked ? Option.some(markerPath) : Option.none(); diff --git a/apps/server/src/holdWork.boot.test.ts b/apps/server/src/holdWork.boot.test.ts index e8937b67548ca..431ef85866f93 100644 --- a/apps/server/src/holdWork.boot.test.ts +++ b/apps/server/src/holdWork.boot.test.ts @@ -266,20 +266,24 @@ const ready = async (root: string, started: Boot) => { return read() ?? {}; }; -/** The names of the spans the server wrote to its trace file, from byte `from` on. */ +/** The names of the spans the server wrote to its trace file, from byte `from` on, and how often each. */ const spansFrom = (stateDir: string, from: number) => { const tracePath = NodePath.join(stateDir, "logs", "server.trace.ndjson"); const text = NodeFS.existsSync(tracePath) ? NodeFS.readFileSync(tracePath) : Buffer.alloc(0); const names = new Set(); + const counts = new Map(); for (const line of text.subarray(from).toString("utf8").split("\n")) { try { const name = (JSON.parse(line) as { readonly name?: unknown }).name; - if (typeof name === "string") names.add(name); + if (typeof name === "string") { + names.add(name); + counts.set(name, (counts.get(name) ?? 0) + 1); + } } catch { // A blank or partial line. } } - return { names, end: text.length }; + return { names, counts, end: text.length }; }; /** What each hold outside the work gate logs instead of starting. */ @@ -846,6 +850,8 @@ describe("serve --hold-work on a seeded home", () => { expect(marked.output()).not.toMatch(PUBLISHER_STARTED); expect(marked.output()).not.toContain("--hold-work"); expect(markedSpans.names).toContain("HoldWorkConnect.releaseManagedTunnel"); + // T3 Connect and agent activity share the boot's one marker read, so they cannot disagree. + expect(markedSpans.counts.get("HoldWorkConnect.heldCopyMarker")).toBe(1); expect(markedSpans.names).toContain("autoPullProjects"); expect(markedSpans.names).toContain("RemoteDelegation.followOnce"); // A normal boot of the copy leaves its marker as it is. @@ -868,7 +874,9 @@ describe("serve --hold-work on a seeded home", () => { await stop(normal.child); // Its tunnel registration waits a random part of half a minute, but stopping releases the // tunnel at once: the relay has the release itself. - const normalSpans = spansFrom(paths.stateDir, markedSpans.end).names; + const normalSpanCounts = spansFrom(paths.stateDir, markedSpans.end); + const normalSpans = normalSpanCounts.names; + expect(normalSpanCounts.counts.get("HoldWorkConnect.heldCopyMarker")).toBe(1); expect(normalSpans).toContain("environment.cloud.releaseManagedTunnelOnShutdown"); expect(tunnelReleases(remote)).toHaveLength(1); expect(NodeFS.existsSync(marker)).toBe(false); diff --git a/docs/fork/updates.md b/docs/fork/updates.md index 5d805529a8044..304aa50acc8a5 100644 --- a/docs/fork/updates.md +++ b/docs/fork/updates.md @@ -285,7 +285,9 @@ settings files may still exist; it moves with the add-ons. `t3 serve --hold-work --base-dir ` starts a server on a copy of a T3 home with the work gate (`apps/server/src/workAdmission.ts`) held from boot until exit. Use it to look at a new build's threads, settings and migrations before it replaces a running T3. It is refused for the background -service. +service, without `--base-dir`, and on the default home (`~/.t3`, also through a symlink), before it +starts or writes anything: a held boot marks its home as a copy (below), and on the live home that +would hold its T3 Connect at every later boot. `T3CODE_HOME` alone does not name the home for it. Held (nothing of it starts until the server restarts without the flag, except T3 Connect: see below): @@ -312,8 +314,9 @@ Held (nothing of it starts until the server restarts without the flag, except T3 - Every boot of that home holds T3 Connect and agent activity publishing as above, with or without `--hold-work`, and logs the marker's path. A copy started normally (`t3 serve` or `t3 up` on its home) runs its work but never registers or releases the tunnel under the shared environment id. - The server reads the marker once as it starts: one added while it runs counts from its next - start. + The server reads the marker once as it starts, and T3 Connect and agent activity publishing + share that one read, so they always agree. A marker added or deleted while it runs counts from + its next start. - `t3 connect login`, `link`, `unlink` and `logout`, `t3 connect publish` turning publishing on, and `t3 up` turning T3 Connect on or off are refused on that home, running or not, before they send anything or change the link or sign-in (the CLI may still create the home's folders and @@ -322,11 +325,15 @@ Held (nothing of it starts until the server restarts without the flag, except T3 the copied sign-in, which the running server shares. Anything at that path counts, even an empty file or a dangling symlink, and so does a path that - cannot be checked. If the home is not a copy, delete the file and run the command or start the + cannot be checked (a disk or permission error holds T3 Connect for that boot, on purpose). If the home is not a copy, delete the file and run the command or start the server again. - A copy with no marker is not protected: one that has never booted held, or one held-booted only by - a build from before the marker (its first held boot on a newer build marks it). Neither the CLI + A copy with no marker is not protected: one that has never booted held, one held-booted only by + a build from before the marker (its first held boot on a newer build marks it), or one copied with + only `userdata/` from a marked copy (as the go-live kit's `copy` step copies). The marker sits in + the home, beside `userdata/`, while the shared identity sits in `userdata/`: such a copy carries + the identity but not the marker. (That is also why restoring `userdata/` can never bring the + marker into the live home.) Neither the CLI nor the server can tell it from the running server's home: never run those commands against it or start it normally. Delete the copy's home instead. From efee08366e4ef93b76f3289f89b72e3b00a6805f Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Wed, 18 Nov 2026 16:04:38 +0000 Subject: [PATCH 2/2] hold-work: refuse the account's home, same-folder identity, symlinked parents (#439) Fix round 1 for the default-home refusal of `serve --hold-work`: - also refuse `.t3` under the passwd home (os.userInfo), so a scratch $HOME does not let `--base-dir /.t3` through; - when both folders exist, compare dev+ino as well as paths, for case-insensitive disks and second mounts; - a target not made yet resolves its deepest existing parent, so a symlinked parent cannot reach the default home. Co-Authored-By: Claude Opus 5.5 --- apps/server/src/cli/forkHoldWork.ts | 84 ++++++++++++++++++--- apps/server/src/cli/server.holdWork.test.ts | 73 +++++++++++++++++- 2 files changed, 145 insertions(+), 12 deletions(-) diff --git a/apps/server/src/cli/forkHoldWork.ts b/apps/server/src/cli/forkHoldWork.ts index d3918d5eff23f..0bcaab60749b0 100644 --- a/apps/server/src/cli/forkHoldWork.ts +++ b/apps/server/src/cli/forkHoldWork.ts @@ -1,10 +1,15 @@ +// @effect-diagnostics nodeBuiltinImport:off - the account's home comes from the passwd entry. /** * Fork (go-live kit): the refusals `t3 serve --hold-work` runs before config resolution, which * claims a port and creates directories. cli/server.ts calls `refuseHoldWork` once. */ +import * as NodeOS from "node:os"; + +import * as Context from "effect/Context"; import * as Effect from "effect/Effect"; import * as FileSystem from "effect/FileSystem"; import * as Option from "effect/Option"; +import * as Path from "effect/Path"; import * as CliError from "effect/cli/CliError"; import { resolveServiceLauncherMode } from "../cloud/serviceLauncherClient.ts"; @@ -38,10 +43,57 @@ const defaultHomeRefusal = (detail: string) => ].join("\n"), }); +/** The account's home from its passwd entry, which ignores `$HOME` (null when there is none). */ +export const AccountHomeDirectory = Context.Reference( + "t3/cli/forkHoldWork/AccountHomeDirectory", + { + defaultValue: () => { + try { + return NodeOS.userInfo().homedir || null; + } catch { + return null; + } + }, + }, +); + /** - * `--hold-work` marks the home it runs on as a copy (cloud/holdWorkConnect.ts), so it needs a home - * named with `--base-dir`, and never the default home (`~/.t3`), which is the live one on most - * machines. `T3CODE_HOME` alone does not count: it is set in a shell, not written on the command. + * The real path of `path`, also when it does not exist yet: the deepest folder that exists is + * resolved and the rest appended, so a symlinked parent cannot hide a home not made yet. + */ +const realPathOrParent = Effect.fn("cli.forkHoldWork.realPathOrParent")(function* (path: string) { + const fs = yield* FileSystem.FileSystem; + const { basename, dirname, join } = yield* Path.Path; + const rest: Array = []; + let current = path; + for (;;) { + const real = yield* fs.realPath(current).pipe(Effect.option); + if (Option.isSome(real)) return join(real.value, ...rest.toReversed()); + const parent = dirname(current); + if (parent === current) return path; + rest.push(basename(current)); + current = parent; + } +}); + +/** The same folder by identity (device and inode), for spellings and mounts a path cannot show. */ +const sameFolder = Effect.fn("cli.forkHoldWork.sameFolder")(function* (a: string, b: string) { + const fs = yield* FileSystem.FileSystem; + const both = yield* Effect.all([fs.stat(a), fs.stat(b)]).pipe(Effect.option); + if (Option.isNone(both)) return false; + const [left, right] = both.value; + return ( + left.dev === right.dev && + Option.isSome(left.ino) && + Option.isSome(right.ino) && + left.ino.value === right.ino.value + ); +}); + +/** + * `--hold-work` marks its home as a copy (cloud/holdWorkConnect.ts): it needs `--base-dir` (not + * just `T3CODE_HOME`) and never a default home, `$HOME/.t3` or the account's own `.t3`, since a + * scratch `$HOME` does not move the live one. */ export const refuseHoldWorkOnDefaultHome = Effect.fn("cli.refuseHoldWorkOnDefaultHome")(function* ( baseDirFlag: Option.Option, @@ -50,15 +102,25 @@ export const refuseHoldWorkOnDefaultHome = Effect.fn("cli.refuseHoldWorkOnDefaul if (Option.isNone(named)) { return yield* defaultHomeRefusal("without --base-dir: it would run on this machine's T3 home"); } + const { join } = yield* Path.Path; const home = yield* resolveBaseDir(named.value); - const defaultHome = yield* resolveBaseDir(undefined); - // A symlink to the default home is the default home: compare real paths when both exist. - const fs = yield* FileSystem.FileSystem; - const real = (path: string) => fs.realPath(path).pipe(Effect.orElseSucceed(() => path)); - if (home === defaultHome || (yield* real(home)) === (yield* real(defaultHome))) { - return yield* defaultHomeRefusal( - `on the default T3 home (${defaultHome}): it is the live one on most machines`, - ); + const accountHome = yield* AccountHomeDirectory; + const defaultHomes = [ + yield* resolveBaseDir(undefined), + ...(accountHome === null ? [] : [join(accountHome, ".t3")]), + ]; + const realHome = yield* realPathOrParent(home); + for (const defaultHome of defaultHomes) { + // A symlink to the default home is the default home: compare real paths, then identities. + if ( + home === defaultHome || + realHome === (yield* realPathOrParent(defaultHome)) || + (yield* sameFolder(home, defaultHome)) + ) { + return yield* defaultHomeRefusal( + `on the default T3 home (${defaultHome}): it is the live one on most machines`, + ); + } } }); diff --git a/apps/server/src/cli/server.holdWork.test.ts b/apps/server/src/cli/server.holdWork.test.ts index 03ac2a747c5ef..8c5aa6ea9b631 100644 --- a/apps/server/src/cli/server.holdWork.test.ts +++ b/apps/server/src/cli/server.holdWork.test.ts @@ -1,6 +1,7 @@ // @effect-diagnostics nodeBuiltinImport:off - CLI integration uses temporary Node paths. // Fork (go-live kit): `serve --hold-work` is refused for the background service and on the default // home (it would mark the live home as a copy). +import * as NodeOS from "node:os"; import * as NodePath from "node:path"; import * as NodeCrypto from "@effect/platform-node/NodeCrypto"; @@ -22,7 +23,11 @@ import { SERVICE_LAUNCHER_PROTOCOL, } from "../cloud/serviceProtocol.ts"; import { cli } from "../binCli.ts"; -import { refuseHoldWorkForBootService, refuseHoldWorkOnDefaultHome } from "./forkHoldWork.ts"; +import { + AccountHomeDirectory, + refuseHoldWorkForBootService, + refuseHoldWorkOnDefaultHome, +} from "./forkHoldWork.ts"; const launcher = (input: { readonly connected: boolean; readonly context?: string }) => ({ host: { @@ -148,6 +153,72 @@ describe("serve --hold-work needs a home named with --base-dir, never the defaul ), ); + it.effect("refuses the account's own T3 home when $HOME points somewhere else", () => + onHome(() => + Effect.gen(function* () { + // `HOME=/scratch t3 serve --hold-work --base-dir /home//.t3`: $HOME moved, the live + // home did not. The account's home comes from the passwd entry, which ignores $HOME. + const accountHome = NodePath.join(NodeOS.userInfo().homedir, ".t3"); + const message = yield* refusal(Option.some(accountHome)); + expect(message).toContain(`--hold-work is refused on the default T3 home (${accountHome})`); + }), + ), + ); + + it.effect("refuses the account home's .t3, made or not, and nothing beside it", () => + onHome((root) => + Effect.gen(function* () { + const accountHome = NodePath.join(root, "account"); + const live = NodePath.join(accountHome, ".t3"); + const message = yield* refusal(Option.some(live)).pipe( + Effect.provideService(AccountHomeDirectory, accountHome), + ); + expect(message).toContain(`--hold-work is refused on the default T3 home (${live})`); + yield* refuseHoldWorkOnDefaultHome(Option.some(`${live}-copy`)).pipe( + Effect.provideService(AccountHomeDirectory, accountHome), + ); + }), + ), + ); + + it.effect("refuses the same folder under another spelling the path check cannot see", () => + onHome((root) => + Effect.gen(function* () { + // A case-insensitive disk (or a second mount): `/.T3` is `/.t3`, and realPath + // keeps the spelling it was given. Only the folder's identity (dev+ino) shows it. + const fs = yield* FileSystem.FileSystem; + const defaultHome = NodePath.join(root, ".t3"); + yield* fs.makeDirectory(defaultHome); + const upper = NodePath.join(root, ".T3"); + const fold = (path: string) => (path === upper ? defaultHome : path); + const caseInsensitive: FileSystem.FileSystem = { + ...fs, + exists: (path) => fs.exists(fold(path)), + stat: (path) => fs.stat(fold(path)), + realPath: (path) => + fs.realPath(fold(path)).pipe(Effect.as(path === upper ? upper : path)), + }; + const message = yield* refusal(Option.some(upper)).pipe( + Effect.provideService(FileSystem.FileSystem, caseInsensitive), + ); + expect(message).toContain(`--hold-work is refused on the default T3 home (${defaultHome})`); + }), + ), + ); + + it.effect("refuses a default home not made yet, reached through a symlinked parent", () => + onHome((root) => + Effect.gen(function* () { + // No `/.t3` yet: the server would create it through the alias and mark it. + const fs = yield* FileSystem.FileSystem; + yield* fs.symlink(root, NodePath.join(root, "alias")); + const message = yield* refusal(Option.some(NodePath.join(root, "alias", ".t3"))); + expect(message).toContain("--hold-work is refused on the default T3 home"); + assert.isFalse(yield* fs.exists(NodePath.join(root, ".t3"))); + }), + ), + ); + it.effect("lets a named copy through, made or not", () => onHome((root) => Effect.gen(function* () {