Skip to content

Commit c612147

Browse files
fix(zmux): worktree dev servers leave the developer's zmux sessions alone (#1913)
## Problem `vp run migrate-dev-db` seeds projects that point at live checkouts. A worktree dev server then binds, attaches to, or could clean up the developer's real zmux sessions. ## Change - **Switch:** `T3CODE_ZMUX_DISABLED=1` disables zmux - **Binder:** every operation returns `disabled` - **Terminals:** fall back to a plain shell - **Dev runner:** sets it for worktree state - **Opt back in:** set `T3CODE_ZMUX_DISABLED=0` ## Scope and approval Closes #1909. Ports, process tree, and Electron profile landed in #1911. **Close conditions** - [ ] Worktree dev ignores ambient `T3CODE_PORT` - [ ] Stopping `vp run dev*` stops its process tree - [ ] Dev Electron userData lives in worktree `.t3` - [ ] Worktree dev leaves live zmux sessions alone ## Verification - Binder, dev-runner, terminal tests → exit 0 - Terminal test fails without the fallback - `vp run check:changed` → exit 0 - `vp run fork:ci` → exit 0 Runtime: seeded worktree, `T3CODE_PORT=3773 vp run dev`. 1. Server binds 14677, not 3773 2. Server env: `T3CODE_ZMUX_DISABLED=1` 3. Live zmux: 41 sessions, names and tabs unchanged 4. Tab close: tree gone, ports free Claude Opus 5.5, Claude Code. ## Fork trailers Squashes: - ad5ad65 fix(zmux): worktree dev servers leave the developer's zmux sessions alone - 1099d19 test(zmux): disabled zmux opens plain shells through the terminal manager Fork-Domain: zmux-estate Fork-Tier: bugfix Fork-Upstreamable: no Co-authored-by: donjor <[email protected]>
1 parent 02b9845 commit c612147

6 files changed

Lines changed: 74 additions & 3 deletions

File tree

‎apps/server/src/terminal/Manager.fork.test.ts‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ import {
88
type TerminalSessionSnapshot,
99
type TerminalSummary,
1010
} from "@t3tools/contracts";
11+
import * as HostProcess from "@t3tools/shared/HostProcess";
1112
import * as Deferred from "effect/Deferred";
1213
import * as Effect from "effect/Effect";
1314
import * as Exit from "effect/Exit";
@@ -148,6 +149,29 @@ it.layer(
148149
expect(ptyAdapter.spawnInputs.map((spawn) => spawn.shell)).toEqual(["zmux", "/bin/bash"]);
149150
}),
150151
);
152+
it.effect("opens a plain shell for every request when zmux is disabled", () =>
153+
Effect.gen(function* () {
154+
const processRunner = resolvedZmuxProcessRunner();
155+
const { manager, ptyAdapter } = yield* createManager(5, {
156+
shellResolver: () => "/bin/bash",
157+
terminalSessionMode: "zmux",
158+
}).pipe(Effect.provideService(ProcessRunner.ProcessRunner, processRunner.service));
159+
const disabled = { ...process.env, T3CODE_ZMUX_DISABLED: "1" };
160+
yield* manager
161+
.open(openInput({ worktreePath: process.cwd() }))
162+
.pipe(Effect.provideService(HostProcess.Environment, disabled));
163+
yield* manager
164+
.open(
165+
openInput({ terminalId: "term-2", worktreePath: process.cwd(), sessionModeFork: "zmux" }),
166+
)
167+
.pipe(Effect.provideService(HostProcess.Environment, disabled));
168+
expect(processRunner.inputs).toEqual([]);
169+
expect(ptyAdapter.spawnInputs.map((spawn) => spawn.shell)).toEqual([
170+
"/bin/bash",
171+
"/bin/bash",
172+
]);
173+
}),
174+
);
151175
it.effect("uses fresh activity when deciding whether an unmanaged terminal can retarget", () =>
152176
Effect.gen(function* () {
153177
let running = false;

‎apps/server/src/terminal/SettlementHookShell.fork.ts‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,12 @@
11
// Fork-only (zmux-estate): settle scripts must survive removal of their checkout's
22
// managed session, including when cleanup finishes before the hook terminal opens.
33
import type { TerminalSessionMode } from "@t3tools/contracts";
4+
import * as HostProcess from "@t3tools/shared/HostProcess";
45
import * as Context from "effect/Context";
56
import * as Effect from "effect/Effect";
67

8+
import { zmuxDisabledByEnv } from "../zmux/ZmuxSessionBinder.ts";
9+
710
class SettlementHookShell extends Context.Reference<boolean>(
811
"t3/terminal/SettlementHookShell.fork/SettlementHookShell",
912
{ defaultValue: () => false },
@@ -14,13 +17,13 @@ export const inSettlementHookShellFork = <A, E, R>(
1417
settle: boolean,
1518
) => Effect.provideService(effect, SettlementHookShell, settle);
1619

17-
/** A terminal's chosen mode wins over the default; settle hooks still force a shell. */
20+
/** A terminal's chosen mode wins over the default; settle hooks and disabled zmux force a shell. */
1821
export const terminalModeForSessionFork = (
1922
chosen: TerminalSessionMode | null,
2023
configured: Effect.Effect<TerminalSessionMode>,
2124
) =>
22-
Effect.flatMap(SettlementHookShell, (settle) =>
23-
settle
25+
Effect.flatMap(Effect.all([SettlementHookShell, HostProcess.Environment]), ([settle, env]) =>
26+
settle || zmuxDisabledByEnv(env)
2427
? Effect.succeed("shell" as const)
2528
: chosen === null
2629
? configured

‎apps/server/src/zmux/ZmuxSessionBinder.test.ts‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,7 @@ function makeLayer(
6161
settings: Parameters<typeof ServerSettings.ServerSettingsService.layerTest>[0] = {
6262
terminalSessionMode: "zmux",
6363
},
64+
extraEnv: NodeJS.ProcessEnv = {},
6465
) {
6566
return ZmuxSessionBinder.layer.pipe(
6667
Layer.provide(Layer.succeed(ProcessRunner.ProcessRunner, { run })),
@@ -74,12 +75,28 @@ function makeLayer(
7475
KEEP_ME: "yes",
7576
TMUX: "/tmp/tmux/default",
7677
TMUX_PANE: "%7",
78+
...extraEnv,
7779
}),
7880
),
7981
);
8082
}
8183

8284
describe("ZmuxSessionBinder", () => {
85+
it.effect("never runs zmux, cleanup included, while T3CODE_ZMUX_DISABLED=1", () => {
86+
const run = vi.fn(() => Effect.succeed(successfulOutput));
87+
88+
return Effect.gen(function* () {
89+
const binder = yield* ZmuxSessionBinder.ZmuxSessionBinder;
90+
assert.deepStrictEqual(yield* binder.bind("/repo/wt"), { status: "disabled" });
91+
assert.deepStrictEqual(yield* binder.prepareUnbind("/repo/wt"), { status: "disabled" });
92+
assert.deepStrictEqual(
93+
yield* binder.unbind({ target: "rsi/wt", nativeId: "$1", serverId: "s", createdAt: 1 }),
94+
{ status: "disabled" },
95+
);
96+
assert.equal(run.mock.calls.length, 0);
97+
}).pipe(Effect.provide(makeLayer(run, undefined, { T3CODE_ZMUX_DISABLED: "1" })));
98+
});
99+
83100
it.effect("binds an existing worktree with tmux routing variables stripped", () => {
84101
const run = vi.fn((input: ProcessRunner.ProcessRunInput) =>
85102
Effect.succeed({

‎apps/server/src/zmux/ZmuxSessionBinder.ts‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -247,10 +247,26 @@ const failureDetail = Effect.fn("ZmuxSessionBinder.failureDetail")(function* (
247247
.join("; ");
248248
});
249249

250+
/** Worktree dev servers default this on: seeded projects point at the developer's live sessions. */
251+
export const zmuxDisabledByEnv = (env: NodeJS.ProcessEnv) => env.T3CODE_ZMUX_DISABLED === "1";
252+
250253
const make = Effect.gen(function* () {
251254
const processRunner = yield* ProcessRunner.ProcessRunner;
252255
const serverSettings = yield* ServerSettings.ServerSettingsService;
253256
const hostEnvironment = yield* HostProcess.Environment;
257+
if (zmuxDisabledByEnv(hostEnvironment)) {
258+
const disabled = Effect.fn("ZmuxSessionBinder.disabled")(() =>
259+
Effect.succeed({ status: "disabled" } as const),
260+
);
261+
return ZmuxSessionBinder.of({
262+
bind: disabled,
263+
ensure: disabled,
264+
reconcileExisting: disabled,
265+
resolve: disabled,
266+
prepareUnbind: disabled,
267+
unbind: disabled,
268+
});
269+
}
254270
const path = yield* Path.Path;
255271
const fileSystem = yield* FileSystem.FileSystem;
256272
const crypto = yield* Crypto.Crypto;

‎scripts/dev-runner.fork.test.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,4 +114,14 @@ it.layer(NodeServices.layer)("dev-runner (fork)", (it) => {
114114
assert.equal(kept?.T3CODE_DEV_ELECTRON_USER_DATA, "/tmp/mine");
115115
}).pipe(Effect.scoped),
116116
);
117+
it.effect("disables zmux for worktree state unless opted back in", () =>
118+
Effect.gen(function* () {
119+
const cwd = yield* makeWorktree;
120+
assert.equal((yield* spawnedEnv({ cwd }))?.T3CODE_ZMUX_DISABLED, "1");
121+
const optIn = { T3CODE_ZMUX_DISABLED: "0" };
122+
assert.equal((yield* spawnedEnv({ cwd, ambient: optIn }))?.T3CODE_ZMUX_DISABLED, "0");
123+
const explicit = yield* spawnedEnv({ cwd, t3Home: "/tmp/explicit-home" });
124+
assert.isUndefined(explicit?.T3CODE_ZMUX_DISABLED);
125+
}).pipe(Effect.scoped),
126+
);
117127
});

‎scripts/dev-runner.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -759,6 +759,7 @@ export const runDevRunnerWithInput = Effect.fn("dev-runner.runDevRunnerWithInput
759759
if (worktreeHome !== undefined && baseDir === worktreeHome) {
760760
env.T3CODE_DEV_ELECTRON_USER_DATA ??= (yield* Path.Path).join(worktreeHome, "electron");
761761
}
762+
if (baseDir === worktreeHome) env.T3CODE_ZMUX_DISABLED ??= "1"; // fork-hook: zmux-estate/dev-runner-zmux-disabled
762763

763764
yield* Effect.logInfo(
764765
`[dev-runner] mode=${input.mode} source=${source}${selectionSuffix} serverPort=${String(env.T3CODE_PORT)} webPort=${String(env.PORT)} baseDir=${baseDir}`,

0 commit comments

Comments
 (0)