Skip to content

Commit aa22745

Browse files
donjor-agent[bot]donjor
authored andcommitted
fix(server): settle checkout-owned zmux sessions (#1665)
# Settle checkout-owned zmux sessions Settling a worktree lane removes its idle checkout-owned zmux session; unsettling restores it through `zmux wt`. The base checkout and `main` session survive settlement. ## Change The server releases managed attachments, confirms their exits, and removes only the exact owned session under a checkout-state lease. Active shared consumers, external viewers, busy shells, and unverifiable ownership preserve the session. Worktrees and branches remain intact. | Review finding | Correction | | --- | --- | | A1: shared checkout identity | Resolve the VCS root and physical path, including subdirectories, symlink aliases, and cross-project consumers | | A2: settle-hook teardown race | Run settle hooks in plain shells; deterministic tests cover cleanup before opening and after hook start, observer completion, and failure retention | ## Verification Head: `e674cef297713ea4da8d3d4067c806335aa5a86f`. One logical commit, rebased onto the CI prerequisite repair from #1666, then published with the explicit old-head lease. | Command | Result | | --- | --- | | `vp test run` on six focused server files | exit 0; 67 tests | | `cd apps/server && vp run typecheck` | exit 0 | | `cd apps/server && vp run build:bundle` | exit 0 | | `vp run fork:ci` | exit 0, including the scripts suite | | Modified guide Markdown lint | exit 0 | Web exercised in isolated `.t3` state on the caller-owned Hypr virtual monitor, with the right-side zmux terminal open. Desktop, mobile, and remote clients use this server lifecycle; they were not independently exercised. No provider adapter or wire-contract change. The latest-head CI and Aftercare verdict remain separate from these local results. ## Proof After a host restart, one Ghostty window and T3's open managed terminal were recorded together on the isolated Hypr virtual monitor. Ghostty removes `proof/settlement` on settle and restores it on unsettle; `main` remains. T3 retains the old terminal bar and prompt, which is tracked separately in #1671. https://github.com/user-attachments/assets/8066e5b5-f09b-4f47-b0a1-2954dd84dd83 Final clip: 10.93 seconds at normal speed, watched end to end without a decode error. Only six seconds of idle setup were cut from the beginning; the settle/unsettle sequence is continuous. ![Ghostty removes the lane while T3 retains the old bar and prompt](https://github.com/user-attachments/assets/6b6497d3-c696-4c80-abf2-4aa82df27553) Independent process checks before the restart verified session `$339`, panes `%667`/`%674`, and shell PIDs `227194`/`3984656` were gone by the first check, 0.8 seconds after settlement began, and still absent 39 seconds later. Main `$175` survived; unsettle created fresh session `$340`, pane `%675`, PID `4073514`. The post-restart clip reproduced native removal and restoration as sessions `$6` and `$7`. <details> <summary>Native evidence and before/after</summary> | Observation | Feature | Main | | --- | --- | --- | | Before UI settle | `$336` | `$175` | | After UI settle, before refresh | Absent; resolution exit 1 | `$175` | | After UI unsettle | `$337` | `$175` | | Base thread settled | `$337` | `$175` | | Active subdirectory and alias consumers | Same `$254` until the last consumer settles | Preserved | The separate command-driven take confirms removal and eventual restoration as `$339`; its immediate unsettle receipt precedes asynchronous restoration. The hook records `HOOK_STARTED` while the native session is absent, then `HOOK_COMPLETED` after gate release. ![Before: settling leaves the feature session](https://github.com/user-attachments/assets/cddef333-c345-452c-ad08-a9d6c1b10332) ![After: feature settled; native receipt confirms absence](https://github.com/user-attachments/assets/9bfdf67c-d5e9-4e1a-9c5d-f2bb9a0a741b) [Receipts and check logs](https://github.com/user-attachments/files/33192532/settlement-receipts.zip) contain the native inventory, hook log, accepted grounding envelope, build identity, checks, and eight recovered skill-read tool receipts with original item IDs and timestamps. The skill receipts are an explicitly selected historical subset, not the whole transcript. </details> Maintainer-authorized implementation, evidence update, and squash merge. Final corrections and verification: GPT-6.1-Sol, Codex harness in T3 Code; inherited implementation: GPT-6.1-Sol and GLM-5.3-Flash in Pi. ## Fork trailers Squashes: - 5c15ad3 fix(server): settle checkout-owned zmux sessions (#1665) (#1665) - 81234fa fixup! fix(server): settle checkout-owned zmux sessions (#1665) (#1665) - bcac190 fix(server): settle checkout-owned zmux sessions (#1665) (#1665) - b66af21 fixup! fix(server): settle checkout-owned zmux sessions (#1665) (#1665) Fork-Domain: zmux-estate Fork-Tier: qol Co-authored-by: donjor <[email protected]>
1 parent adf496d commit aa22745

17 files changed

Lines changed: 1520 additions & 24 deletions

‎apps/server/src/orchestration-v2/EventSink.ts‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ import * as Schema from "effect/Schema";
2323
import * as Stream from "effect/Stream";
2424
import * as SqlClient from "effect/sql/SqlClient";
2525

26+
import { withCheckoutSessionMutationFork } from "../zmux/CheckoutSessionStateLease.fork.ts"; // fork-hook: zmux-estate/settlement-state-lease-import
2627
import { replayAndBufferProjectedLiveEvents } from "./LiveStreamBudget.ts";
2728
import type { UnsequencedProjectEvent } from "../persistence/OrchestrationEventStore.ts";
2829
import { projectDomainEventForWire } from "./WireProjection.ts";
@@ -280,14 +281,16 @@ const layerBase: Layer.Layer<
280281
// Cancellation may roll back the transaction's work. Once it commits,
281282
// every subscriber must hear about it before this writer can exit.
282283
// Otherwise a failed child run can leave its parent's task running.
283-
return sql
284-
.withTransaction(Effect.tap(restore(transaction), () => takeLane))
285-
.pipe(
286-
Effect.tap(publish),
287-
Effect.ensuring(
288-
Effect.suspend(() => (holdsLane ? publishLane.release(1) : Effect.void)),
284+
return withCheckoutSessionMutationFork(
285+
sql
286+
.withTransaction(Effect.tap(restore(transaction), () => takeLane))
287+
.pipe(
288+
Effect.tap(publish),
289+
Effect.ensuring(
290+
Effect.suspend(() => (holdsLane ? publishLane.release(1) : Effect.void)),
291+
),
289292
),
290-
);
293+
); // fork-hook: zmux-estate/settlement-state-commit-lease
291294
});
292295

293296
// A user can answer after terminal normalization reads the pending request.
Lines changed: 300 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,300 @@
1+
import * as NodeServices from "@effect/platform-node/NodeServices";
2+
import { it } from "@effect/vitest";
3+
import {
4+
ProjectId,
5+
ThreadId,
6+
type OrchestrationProjectShell,
7+
type OrchestrationV2AppThread,
8+
type OrchestrationV2ThreadShellSnapshot,
9+
} from "@t3tools/contracts";
10+
import * as Deferred from "effect/Deferred";
11+
import * as Effect from "effect/Effect";
12+
import * as Fiber from "effect/Fiber";
13+
import * as Layer from "effect/Layer";
14+
import * as Option from "effect/Option";
15+
import { expect } from "vite-plus/test";
16+
17+
import * as Orchestrator from "../orchestration-v2/Orchestrator.ts";
18+
import * as ProjectStore from "../orchestration-v2/ProjectStore.ts";
19+
import * as ProjectionStore from "../orchestration-v2/ProjectionStore.ts";
20+
import * as ProcessRunner from "../processRunner.ts";
21+
import * as ServerSettings from "../serverSettings.ts";
22+
import * as TerminalManager from "../terminal/Manager.ts";
23+
import {
24+
createManager,
25+
FakeProcessRunner,
26+
processResult,
27+
} from "../terminal/Manager.fork-test-harness.ts";
28+
import * as VcsDriverRegistry from "../vcs/VcsDriverRegistry.ts";
29+
import { makeSettledLaneReactor } from "../zmux/SettledLaneSessions.fork.ts";
30+
import * as Binder from "../zmux/ZmuxSessionBinder.ts";
31+
import * as ProjectService from "./ProjectService.ts";
32+
import * as ProjectSetupScriptRunner from "./ProjectSetupScriptRunner.ts";
33+
34+
const threadId = ThreadId.make("thread:hook-lifecycle");
35+
const projectId = ProjectId.make("project:hook-lifecycle");
36+
const identity = {
37+
target: "fixture/feature",
38+
nativeId: "$22",
39+
serverId: "123:456",
40+
createdAt: 123,
41+
};
42+
43+
const harness = Effect.gen(function* () {
44+
let available = true;
45+
let settled = true;
46+
let busy = true;
47+
let beforeOpen: Effect.Effect<void> = Effect.void;
48+
const processRunner = new FakeProcessRunner(() =>
49+
Effect.succeed(
50+
processResult({
51+
stdout: available
52+
? '{"workspace":"fixture","session":"feature","target":"fixture/feature","tmuxName":"zws_fixture__feature","nativeId":"$22","serverId":"123:456","createdAt":123,"state":"live","match":"worktree"}'
53+
: '{"status":"not-found"}',
54+
}),
55+
),
56+
);
57+
const fixture = yield* createManager(20, {
58+
terminalSessionMode: "zmux",
59+
shellResolver: () => "/bin/bash",
60+
subprocessInspector: () =>
61+
Effect.succeed({
62+
hasRunningSubprocess: busy,
63+
childCommand: busy ? "hook" : null,
64+
processIds: [],
65+
}),
66+
resolveOnlyForSettledThread: () => Effect.sync(() => settled),
67+
ensureZmuxSession: () =>
68+
Effect.succeed({
69+
status: "ensured",
70+
target: "fixture/feature",
71+
workspace: "fixture",
72+
session: "feature",
73+
}),
74+
}).pipe(Effect.provideService(ProcessRunner.ProcessRunner, processRunner.service));
75+
const patched = new Set<number>();
76+
const acknowledgeKills = () => {
77+
for (const process of fixture.ptyAdapter.processes) {
78+
if (patched.has(process.pid)) continue;
79+
patched.add(process.pid);
80+
const kill = process.kill.bind(process);
81+
process.kill = (signal) => {
82+
kill(signal);
83+
process.emitExit({ exitCode: 0, signal: 15 });
84+
};
85+
}
86+
};
87+
const terminals = TerminalManager.TerminalManager.of({
88+
...fixture.manager,
89+
open: (input) =>
90+
beforeOpen.pipe(
91+
Effect.andThen(fixture.manager.open(input)),
92+
Effect.tap(() => Effect.sync(acknowledgeKills)),
93+
),
94+
});
95+
const project = {
96+
id: projectId,
97+
workspaceRoot: fixture.baseDir,
98+
scripts: [
99+
{
100+
id: "setup",
101+
name: "Setup",
102+
command: "printf setup",
103+
icon: "configure",
104+
runOnWorktreeCreate: true,
105+
},
106+
{
107+
id: "hook",
108+
name: "Settle",
109+
command: "printf hook",
110+
icon: "configure",
111+
runOnWorktreeCreate: false,
112+
runOnSettle: true,
113+
},
114+
],
115+
} satisfies NonNullable<ProjectSetupScriptRunner.ProjectSetupScriptRunnerInput["project"]>;
116+
const thread = {
117+
id: threadId,
118+
projectId,
119+
worktreePath: process.cwd(),
120+
archivedAt: null,
121+
settledOverride: "settled",
122+
} as OrchestrationV2AppThread;
123+
const dependencies = Layer.mergeAll(
124+
Layer.succeed(TerminalManager.TerminalManager, terminals),
125+
ServerSettings.layerTest(),
126+
Layer.mock(ProjectService.ProjectService)({}),
127+
Layer.mock(ProjectStore.ProjectStoreV2)({
128+
getShell: () =>
129+
Effect.succeed(
130+
Option.some({ workspaceRoot: fixture.baseDir } as OrchestrationProjectShell),
131+
),
132+
}),
133+
Layer.mock(ProjectionStore.ProjectionStoreV2)({ getThread: () => Effect.succeed(thread) }),
134+
Layer.mock(Orchestrator.OrchestratorV2)({
135+
getShellSnapshot: () =>
136+
Effect.succeed({ threads: [thread] } as unknown as OrchestrationV2ThreadShellSnapshot),
137+
}),
138+
Layer.mock(VcsDriverRegistry.VcsDriverRegistry)({
139+
resolve: ({ cwd }) =>
140+
Effect.succeed({ repository: { rootPath: cwd } } as VcsDriverRegistry.VcsDriverHandle),
141+
}),
142+
Layer.mock(Binder.ZmuxSessionBinder)({
143+
prepareUnbind: () => Effect.succeed({ status: "prepared", identity }),
144+
resolve: () =>
145+
Effect.succeed({ status: "resolved", target: "fixture/main", match: "workspace-main" }),
146+
unbind: () =>
147+
Effect.sync(() => {
148+
available = false;
149+
return { status: "unbound", target: identity.target } as const;
150+
}),
151+
}),
152+
);
153+
const reactor = yield* makeSettledLaneReactor.pipe(Effect.provide(dependencies));
154+
const runner = yield* ProjectSetupScriptRunner.make.pipe(Effect.provide(dependencies));
155+
// The runner types once the shell's line editor starts, so the fake shell signals it.
156+
const runHook = (trigger: "setup" | "settle" = "settle") =>
157+
Effect.gen(function* () {
158+
const run = yield* runner.runForThread({
159+
threadId,
160+
projectId,
161+
project,
162+
worktreePath: process.cwd(),
163+
trigger,
164+
observeCompletion: {},
165+
});
166+
const shell = fixture.ptyAdapter.processes.at(-1)!;
167+
const typed = Promise.withResolvers<void>();
168+
const write = shell.write.bind(shell);
169+
shell.write = (data) => {
170+
write(data);
171+
typed.resolve();
172+
};
173+
shell.emitData("fixture$ \x1b[?2004h");
174+
yield* Effect.promise(() => typed.promise);
175+
return run;
176+
});
177+
const finishHook = (
178+
run: ProjectSetupScriptRunner.ProjectSetupScriptRunnerResult,
179+
exitCode: number,
180+
) =>
181+
Effect.gen(function* () {
182+
if (run.status !== "started" || !run.completion)
183+
return yield* Effect.die("hook did not start with observation");
184+
const process = fixture.ptyAdapter.processes.at(-1)!;
185+
const sentinel = /(__T3_SETUP_DONE___\w+:)/.exec(process.writes.at(-1) ?? "")?.[1];
186+
if (!sentinel) return yield* Effect.die("missing completion sentinel");
187+
busy = false;
188+
const completion = yield* Effect.forkChild(run.completion);
189+
process.emitData(`\r\n${sentinel}${exitCode}\r\nfixture$ `);
190+
return yield* Fiber.join(completion);
191+
});
192+
return {
193+
fixture,
194+
processRunner,
195+
runHook,
196+
finishHook,
197+
cleanup: reactor.reconcile(threadId),
198+
inventory: () => (available ? ["fixture/main", "fixture/feature"] : ["fixture/main"]),
199+
setSettled: (value: boolean) => {
200+
settled = value;
201+
},
202+
setBeforeOpen: (effect: Effect.Effect<void>) => {
203+
beforeOpen = effect;
204+
},
205+
openViewer: Effect.gen(function* () {
206+
settled = false;
207+
const release = yield* fixture.manager.attachStream(
208+
{
209+
threadId,
210+
terminalId: "viewer",
211+
cwd: process.cwd(),
212+
worktreePath: process.cwd(),
213+
cols: 100,
214+
rows: 24,
215+
},
216+
() => Effect.void,
217+
);
218+
acknowledgeKills();
219+
settled = true;
220+
return release;
221+
}),
222+
};
223+
});
224+
225+
it.layer(NodeServices.layer, { excludeTestServices: true })(
226+
"settle-hook session teardown",
227+
(it) => {
228+
it.effect(
229+
"cleanup can finish before the configured hook opens without preventing completion",
230+
() =>
231+
Effect.gen(function* () {
232+
const h = yield* harness;
233+
const opening = yield* Deferred.make<void>();
234+
const allowOpen = yield* Deferred.make<void>();
235+
h.setBeforeOpen(
236+
Deferred.succeed(opening, undefined).pipe(Effect.andThen(Deferred.await(allowOpen))),
237+
);
238+
const hook = yield* Effect.forkChild(h.runHook());
239+
yield* Deferred.await(opening);
240+
yield* h.cleanup;
241+
expect(h.inventory()).toEqual(["fixture/main"]);
242+
yield* Deferred.succeed(allowOpen, undefined);
243+
const run = yield* Fiber.join(hook);
244+
expect(h.fixture.ptyAdapter.spawnInputs.at(-1)?.shell).toBe("/bin/bash");
245+
expect(h.processRunner.inputs.filter((input) => input.command === "zmux")).toEqual([]);
246+
expect((yield* h.finishHook(run, 0)).exitCode).toBe(0);
247+
expect((yield* h.fixture.getEvents).some((event) => event.type === "closed")).toBe(true);
248+
}),
249+
);
250+
251+
it.effect(
252+
"cleanup after hook start releases the managed viewer but keeps hook observation alive",
253+
() =>
254+
Effect.gen(function* () {
255+
const h = yield* harness;
256+
const releaseViewer = yield* h.openViewer;
257+
const run = yield* h.runHook();
258+
const hook = h.fixture.ptyAdapter.processes.at(-1)!;
259+
const completion =
260+
run.status === "started" && run.completion
261+
? yield* Effect.forkChild(run.completion)
262+
: yield* Effect.die("missing hook completion");
263+
yield* h.cleanup;
264+
expect(h.inventory()).toEqual(["fixture/main"]);
265+
expect(h.fixture.ptyAdapter.processes[0]?.killSignals).toContain("SIGTERM");
266+
expect(hook.killSignals).toEqual([]);
267+
expect(hook.hasDataListener()).toBe(true);
268+
expect(completion.pollUnsafe()).toBeUndefined();
269+
// The observer is evaluated once; its completion effect is passed to the helper.
270+
if (run.status !== "started") return yield* Effect.die("missing hook");
271+
expect(
272+
(yield* h.finishHook({ ...run, completion: Fiber.join(completion) }, 0)).exitCode,
273+
).toBe(0);
274+
releaseViewer();
275+
}),
276+
);
277+
278+
it.effect("failed hook remains inspectable after session removal", () =>
279+
Effect.gen(function* () {
280+
const h = yield* harness;
281+
const run = yield* h.runHook();
282+
yield* h.cleanup;
283+
expect((yield* h.finishHook(run, 7)).exitCode).toBe(7);
284+
expect(h.fixture.ptyAdapter.processes.at(-1)?.killSignals).toEqual([]);
285+
expect(h.inventory()).toEqual(["fixture/main"]);
286+
yield* h.fixture.manager.close({ threadId });
287+
}),
288+
);
289+
290+
it.effect("setup scripts still attach to the configured managed session", () =>
291+
Effect.gen(function* () {
292+
const h = yield* harness;
293+
h.setSettled(false);
294+
yield* h.runHook("setup");
295+
expect(h.fixture.ptyAdapter.spawnInputs[0]?.args).toContain("open");
296+
yield* h.fixture.manager.close({ threadId });
297+
}),
298+
);
299+
},
300+
);

‎apps/server/src/project/ProjectSetupScriptRunner.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ import * as Schema from "effect/Schema";
2020
import * as ProjectionStore from "../orchestration-v2/ProjectionStore.ts";
2121
import * as ServerSettings from "../serverSettings.ts";
2222
import * as TerminalManager from "../terminal/Manager.ts";
23+
import { inSettlementHookShellFork } from "../terminal/SettlementHookShell.fork.ts"; // fork-hook: zmux-estate/settle-hook-shell-import
2324
import * as ProjectService from "./ProjectService.ts";
2425

2526
export interface ProjectSetupScriptRunnerResultNoScript {
@@ -565,6 +566,7 @@ export const make = Effect.gen(function* () {
565566
env: { ...env, NO_COLOR: "1", FORCE_COLOR: "0" },
566567
})
567568
.pipe(
569+
(effect) => inSettlementHookShellFork(effect, trigger === "settle"), // fork-hook: zmux-estate/settle-hook-shell-open
568570
Effect.mapError(
569571
(cause) =>
570572
new ProjectSetupScriptOperationError({

‎apps/server/src/server.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -128,6 +128,8 @@ import * as GitWorkflowService from "./git/GitWorkflowService.ts";
128128
import * as CheckoutMutationCoordinator from "./git/CheckoutMutationCoordinator.ts";
129129
import { checkoutMoveServiceLiveFork } from "./git/CheckoutMoveService.fork.ts"; // fork-hook: zmux-estate/server-checkout-move-import
130130
import { checkoutHeadFollowLiveFork } from "./git/CheckoutHeadFollow.fork.ts"; // fork-hook: zmux-estate/server-checkout-head-follow-import
131+
import { settledLaneSessionReactorLiveFork } from "./zmux/SettledLaneSessions.fork.ts"; // fork-hook: zmux-estate/server-settled-lane-sessions-import
132+
import * as SettledLaneAttachGuard from "./zmux/SettledLaneAttachGuard.fork.ts"; // fork-hook: zmux-estate/server-settled-lane-guard-import
131133
import * as ReviewService from "./review/ReviewService.ts";
132134
import * as SourceControlProviderRegistry from "./sourceControl/SourceControlProviderRegistry.ts";
133135
import * as PullRequestReadCache from "./pullRequest/PullRequestReadCache.ts";
@@ -469,6 +471,7 @@ const layerTerminal = TerminalManager.layer.pipe(
469471
Layer.provide(layerNativeTelemetry),
470472
Layer.provide(layerServerSettings),
471473
Layer.provide(ZmuxSessionBinderLayerLive),
474+
Layer.provide(SettledLaneAttachGuard.layer), // fork-hook: zmux-estate/server-settled-lane-attach-guard
472475
);
473476

474477
const layerPreview = Layer.empty.pipe(
@@ -654,6 +657,7 @@ const layerRuntimeCoreDependenciesBase = Layer.mergeAll(
654657
threadIssueSyncReactorLiveFork, // fork-hook: github-issues/server-issue-sync-reactor
655658
checkoutMoveServiceLiveFork, // fork-hook: zmux-estate/server-checkout-move-service
656659
checkoutHeadFollowLiveFork, // fork-hook: zmux-estate/server-checkout-head-follow
660+
settledLaneSessionReactorLiveFork.pipe(Layer.provide(ZmuxSessionBinderLayerLive)), // fork-hook: zmux-estate/server-settled-lane-sessions-reactor
657661
).pipe(
658662
Layer.provideMerge(layerOrchestrationApplication),
659663
Layer.provideMerge(RuntimeLayer.layerEventInfrastructure),

0 commit comments

Comments
 (0)