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 22, 03:15 UTC
feat(server): stop opted-in project actions when threads settle (#31857)
Yash Singh committed
Nov 6, 2026 at 01:20 UTC
dd059b40bcf0d8dccc9f575b9dca6551c5c0dc45
23 files changed
+125
-34
apps/mobile/src/features/terminal/ThreadTerminalRouteScreen.tsx
+1
@@ -487,6 +487,7 @@ function ThreadTerminal(props: {
487
cols: initialAttachGridSize.cols,
488
rows: initialAttachGridSize.rows,
489
...(pendingLaunch?.env ? { env: pendingLaunch.env } : {}),
490
+ ...(pendingLaunch ? { stopOnSettle: pendingLaunch.stopOnSettle ?? false } : {}),
491
...(pendingLaunch ? { restartIfNotRunning: true } : {}),
492
}
493
: null,
apps/mobile/src/features/terminal/terminalLaunchContext.ts
+2
@@ -17,6 +17,7 @@ export interface PendingTerminalLaunch {
17
readonly worktreePath: string | null;
18
readonly env?: Record<string, string>;
19
readonly initialInput?: string;
20
+ readonly stopOnSettle?: boolean;
21
}
22
23
const pendingTerminalLaunches = new Map<string, PendingTerminalLaunch>();
@@ -34,6 +35,7 @@ export function stagePendingTerminalLaunch(input: {
35
worktreePath: input.launch.worktreePath,
36
env: input.launch.env ? { ...input.launch.env } : undefined,
37
initialInput: input.launch.initialInput,
38
+ stopOnSettle: input.launch.stopOnSettle,
39
});
40
}
41
apps/mobile/src/features/threads/ThreadRouteScreen.tsx
+1
@@ -767,6 +767,7 @@ function ThreadRouteContent(
767
worktreePath: preferredWorktreePath,
768
env,
769
initialInput: projectScriptTerminalInput(script.command),
770
+ stopOnSettle: script.stopOnSettle ?? false,
771
},
772
});
773
apps/server/src/orchestration-v2/ThreadSettlementService.test.ts
+1
-1
@@ -682,7 +682,7 @@ const makeHarness = Effect.fn("makeThreadSettlementHarness")(function* (options:
682
dispatch,
683
}),
684
Layer.mock(TerminalManager.TerminalManager)({
685
- closeIdle: (input) =>
685
+ closeOnSettle: (input) =>
686
Queue.offer(closedIdle, input).pipe(Effect.andThen(options.onCloseIdle?.() ?? Effect.void)),
687
}),
688
Layer.mock(ProjectSetupScriptRunner.ProjectSetupScriptRunner)({
apps/server/src/orchestration-v2/ThreadSettlementService.ts
+1
-1
@@ -599,7 +599,7 @@ export const make = Effect.gen(function* () {
599
function* (threadId: ThreadId) {
600
const settled = yield* projections.getThread(threadId);
601
if (settled.settledOverride !== "settled") return;
602
- yield* terminals.closeIdle({ threadId });
602
+ yield* terminals.closeOnSettle({ threadId });
603
const worktreePath = settled.worktreePath;
604
if (worktreePath === null || !(yield* fileSystem.exists(worktreePath))) return;
605
// Recheck after closing and worktree I/O; re-engaged threads must not be cleaned up.
apps/server/src/project/ProjectSetupScriptRunner.test.ts
+1
@@ -62,6 +62,7 @@ const makeHarness = Effect.fn(function* (options: {
62
}),
63
write: (input) => Queue.offer(writes, input.data).pipe(Effect.asVoid),
64
closeIdle: () => Effect.void,
65
+ closeOnSettle: () => Effect.void,
66
});
67
const runner = yield* ProjectSetupScriptRunner.make.pipe(
68
Effect.provide(
apps/server/src/project/ProjectSetupScriptRunner.ts
+1
@@ -466,6 +466,7 @@ export const make = Effect.gen(function* () {
466
.open({
467
threadId: input.threadId,
468
terminalId,
469
+ stopOnSettle: script.stopOnSettle ?? false,
470
cwd,
471
worktreePath: input.worktreePath,
472
env: { ...env, NO_COLOR: "1", FORCE_COLOR: "0" },
apps/server/src/provider/agentContextBudget.json
+1
-1
@@ -1,5 +1,5 @@
1
{
2
"claudeSystemAppendBytes": 5366,
3
"codexAdditionalContextBytes": 7096,
4
- "mcpToolListJsonBytes": 48051
4
+ "mcpToolListJsonBytes": 48119
5
}
apps/server/src/terminal/Manager.test.ts
+46
-28
@@ -740,34 +740,52 @@ it.layer(
740
}),
741
);
742
743
- it.effect("closes only a thread's idle shells, ignoring a helper forked from the shell", () =>
744
- Effect.gen(function* () {
745
- const { manager, ptyAdapter } = yield* createManager(5, {
746
- processTable: Effect.succeed([
747
- { pid: 9000, ppid: 1, name: "zsh" },
748
- { pid: 100, ppid: 9000, name: "zsh" },
749
- { pid: 9001, ppid: 1, name: "zsh" },
750
- { pid: 200, ppid: 9001, name: "node" },
751
- { pid: 9002, ppid: 1, name: "zsh" },
752
- { pid: 300, ppid: 9002, name: "zsh" },
753
- { pid: 301, ppid: 300, name: "sleep" },
754
- { pid: 9003, ppid: 1, name: "zsh" },
755
- ]),
756
- }).pipe(Effect.provide(layerWithHostPlatform("linux")));
757
- yield* manager.open(openInput({ terminalId: "idle" }));
758
- yield* manager.open(openInput({ terminalId: "dev-server" }));
759
- yield* manager.open(openInput({ terminalId: "subshell" }));
760
- yield* manager.open(openInput({ threadId: "thread-2" }));
761
-
762
- yield* manager.closeIdle({ threadId: "thread-1" });
763
-
764
- expect(ptyAdapter.processes.map((process) => process.killed)).toEqual([
765
- true,
766
- false,
767
- false,
768
- false,
769
- ]);
770
- }),
743
+ it.effect(
744
+ "closes idle shells and opted-in actions on settlement without stopping other commands",
745
+ () =>
746
+ Effect.gen(function* () {
747
+ const { manager, ptyAdapter } = yield* createManager(5, {
748
+ processTable: Effect.succeed([
749
+ { pid: 9000, ppid: 1, name: "zsh" },
750
+ { pid: 100, ppid: 9000, name: "zsh" },
751
+ { pid: 9001, ppid: 1, name: "zsh" },
752
+ { pid: 200, ppid: 9001, name: "node" },
753
+ { pid: 9002, ppid: 1, name: "zsh" },
754
+ { pid: 300, ppid: 9002, name: "zsh" },
755
+ { pid: 301, ppid: 300, name: "sleep" },
756
+ { pid: 9003, ppid: 1, name: "zsh" },
757
+ { pid: 9004, ppid: 1, name: "zsh" },
758
+ { pid: 400, ppid: 9004, name: "node" },
759
+ ]),
760
+ }).pipe(Effect.provide(layerWithHostPlatform("linux")));
761
+ yield* manager.open(openInput({ terminalId: "idle" }));
762
+ yield* manager.open(openInput({ terminalId: "dev-server" }));
763
+ yield* manager.open(openInput({ terminalId: "subshell" }));
764
+ yield* manager.open(openInput({ threadId: "thread-2", stopOnSettle: true }));
765
+ yield* manager.open(openInput({ terminalId: "managed-dev", stopOnSettle: true }));
766
+
767
+ yield* manager.closeIdle({ threadId: "thread-1" });
768
+
769
+ expect(ptyAdapter.processes.map((process) => process.killed)).toEqual([
770
+ true,
771
+ false,
772
+ false,
773
+ false,
774
+ false,
775
+ ]);
776
+ yield* manager.open(openInput({ terminalId: "managed-dev", stopOnSettle: false }));
777
+ yield* manager.closeOnSettle({ threadId: "thread-1" });
778
+ expect(ptyAdapter.processes[4]?.killed).toBe(false);
779
+ yield* manager.open(openInput({ terminalId: "managed-dev", stopOnSettle: true }));
780
+ yield* manager.closeOnSettle({ threadId: "thread-1" });
781
+ expect(ptyAdapter.processes.map((process) => process.killed)).toEqual([
782
+ true,
783
+ false,
784
+ false,
785
+ false,
786
+ true,
787
+ ]);
788
+ }),
789
);
790
791
it.effect("labels a running command by its whole process name, spaces included", () =>
apps/server/src/terminal/Manager.ts
+23
@@ -219,6 +219,8 @@ export class TerminalManager extends Context.Service<
219
/** Omit terminalId to close all sessions for the thread. */
220
readonly close: (input: TerminalCloseInput) => Effect.Effect<void, TerminalError>;
221
222
+ readonly closeOnSettle: (input: { readonly threadId: string }) => Effect.Effect<void>;
223
+
224
readonly closeIdle: (input: {
225
readonly threadId: string;
226
readonly terminalId?: string;
@@ -304,6 +306,7 @@ interface TerminalSessionState {
306
hasRunningSubprocess: boolean;
307
childCommandLabel: string | null;
308
runtimeEnv: Record<string, string> | null;
309
+ stopOnSettle: boolean;
310
}
311
312
interface TerminalGrid {
@@ -2871,6 +2874,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
2874
hasRunningSubprocess: false,
2875
childCommandLabel: null,
2876
runtimeEnv: normalizedRuntimeEnv(input.env),
2877
+ stopOnSettle: input.stopOnSettle ?? false,
2878
};
2879
2880
const createdSession = session;
@@ -2896,6 +2900,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
2900
}
2901
2902
const liveSession = existing.value;
2903
+ if (input.stopOnSettle !== undefined) liveSession.stopOnSettle = input.stopOnSettle;
2904
const nextRuntimeEnv = normalizedRuntimeEnv(input.env);
2905
const currentRuntimeEnv = liveSession.runtimeEnv;
2906
const targetCols = input.cols ?? liveSession.cols;
@@ -3453,6 +3458,23 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
3458
),
3459
);
3460
3461
+ const closeOnSettle = Effect.fn("terminal.closeOnSettle")(function* (input: {
3462
+ readonly threadId: string;
3463
+ }) {
3464
+ yield* withThreadLock(
3465
+ input.threadId,
3466
+ Effect.gen(function* () {
3467
+ const sessions = yield* sessionsForThread(input.threadId);
3468
+ yield* Effect.forEach(
3469
+ sessions.filter((session) => session.stopOnSettle),
3470
+ (session) => closeSession(input.threadId, session.terminalId, false),
3471
+ { discard: true },
3472
+ );
3473
+ }),
3474
+ );
3475
+ yield* closeIdle(input);
3476
+ });
3477
+
3478
return TerminalManager.of({
3479
open,
3480
getShell,
@@ -3465,6 +3487,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
3487
clear,
3488
close,
3489
closeIdle,
3490
+ closeOnSettle,
3491
subscribe,
3492
subscribeMetadata,
3493
});
apps/web/src/components/ProjectScriptsControl.tsx
+1
@@ -137,6 +137,7 @@ export default function ProjectScriptsControl({
137
runOnWorktreeCreate: fileScript.runOnWorktreeCreate ?? false,
138
waitForSetup: fileScript.runOnWorktreeCreate === true && fileScript.async === false,
139
runOnSettle: fileScript.runOnSettle ?? false,
140
+ stopOnSettle: fileScript.stopOnSettle ?? false,
141
...(readEnvironmentScope(environmentId, AuthSettingsWriteScope) ? { keybinding: null } : {}),
142
previewUrl: fileScript.previewUrl ?? null,
143
autoOpenPreview: fileScript.previewUrl ? (fileScript.autoOpenPreview ?? false) : false,
apps/web/src/components/chat/useChatTerminalActions.ts
+2
@@ -218,6 +218,7 @@ export function useChatTerminalActions(input: ChatTerminalActionsInput) {
218
}
219
const targetCwd = options?.cwd ?? gitCwd ?? activeProject.workspaceRoot;
220
const reusableTerminalId =
221
+ script.stopOnSettle ||
222
options?.preferNewTerminal ||
223
!canReuseTerminal ||
224
!readEnvironmentScope(environmentId, AuthTerminalReadScope)
@@ -254,6 +255,7 @@ export function useChatTerminalActions(input: ChatTerminalActionsInput) {
255
? { size: { cols: SCRIPT_TERMINAL_COLS, rows: SCRIPT_TERMINAL_ROWS } }
256
: { terminalId: reusableTerminalId }),
257
location: { cwd: targetCwd, worktreePath: targetWorktreePath },
258
+ stopOnSettle: script.stopOnSettle ?? false,
259
...(options?.env ? { extraEnv: options.env } : {}),
260
});
261
if (!launched) return;
apps/web/src/components/projectScriptEditor.tsx
+12
@@ -85,6 +85,7 @@ export interface NewProjectScriptInput {
85
runOnWorktreeCreate: boolean;
86
waitForSetup: boolean;
87
runOnSettle: boolean;
88
+ stopOnSettle?: boolean;
89
/** Omit to preserve the current shortcut when the form did not edit it. */
90
keybinding?: string | null;
91
previewUrl: string | null;
@@ -100,6 +101,7 @@ export const EMPTY_PROJECT_SCRIPT_INPUT: NewProjectScriptInput = {
101
runOnWorktreeCreate: false,
102
waitForSetup: false,
103
runOnSettle: false,
104
+ stopOnSettle: false,
105
keybinding: null,
106
previewUrl: null,
107
autoOpenPreview: false,
@@ -124,6 +126,7 @@ export function editorRequestForScript(
126
runOnWorktreeCreate: script.runOnWorktreeCreate,
127
waitForSetup: script.runOnWorktreeCreate && script.async === false,
128
runOnSettle: script.runOnSettle ?? false,
129
+ stopOnSettle: script.stopOnSettle ?? false,
130
keybinding: keybindingValueForCommand(keybindings, commandForProjectScript(script.id)),
131
previewUrl: script.previewUrl ?? null,
132
autoOpenPreview: script.autoOpenPreview ?? false,
@@ -275,6 +278,7 @@ function ProjectScriptEditorForm({
278
);
279
const [waitForSetup, setWaitForSetup] = useState(request.initial.waitForSetup);
280
const [runOnSettle, setRunOnSettle] = useState(request.initial.runOnSettle);
281
+ const [stopOnSettle, setStopOnSettle] = useState(request.initial.stopOnSettle ?? false);
282
const [keybinding, setKeybinding] = useState(request.initial.keybinding ?? "");
283
const [previewUrl, setPreviewUrl] = useState(request.initial.previewUrl ?? "");
284
const [autoOpenPreview, setAutoOpenPreview] = useState(request.initial.autoOpenPreview);
@@ -359,6 +363,7 @@ function ProjectScriptEditorForm({
363
runOnWorktreeCreate,
364
waitForSetup: runOnWorktreeCreate && waitForSetup,
365
runOnSettle,
366
+ stopOnSettle,
367
...((request.scriptId === null && canChangeKeybinding) || changesKeybinding
368
? { keybinding: keybindingRule?.key ?? null }
369
: {}),
@@ -521,6 +526,13 @@ function ProjectScriptEditorForm({
526
onCheckedChange={(checked) => setRunOnSettle(Boolean(checked))}
527
/>
528
</label>
529
+ <label className="flex items-center justify-between gap-3 rounded-md border border-border/70 px-3 py-2 text-sm dark:border-transparent dark:bg-white/[0.035]">
530
+ <span>Stop this action when the thread settles</span>
531
+ <Switch
532
+ checked={stopOnSettle}
533
+ onCheckedChange={(checked) => setStopOnSettle(Boolean(checked))}
534
+ />
535
+ </label>
536
<label
537
className={`flex items-center justify-between gap-3 rounded-md border border-border/70 px-3 py-2 text-sm dark:border-transparent dark:bg-white/[0.035] ${
538
previewUrl.trim().length === 0 ? "opacity-60" : ""
apps/web/src/components/settings/ProjectActionsSettings.tsx
+1
@@ -91,6 +91,7 @@ export function ProjectActionsSettings() {
91
runOnWorktreeCreate: fileScript.runOnWorktreeCreate ?? false,
92
waitForSetup: fileScript.runOnWorktreeCreate === true && fileScript.async === false,
93
runOnSettle: fileScript.runOnSettle ?? false,
94
+ stopOnSettle: fileScript.stopOnSettle ?? false,
95
keybinding: null,
96
previewUrl: fileScript.previewUrl ?? null,
97
autoOpenPreview: fileScript.previewUrl ? (fileScript.autoOpenPreview ?? false) : false,
apps/web/src/components/terminal/useThreadTerminalActions.ts
+2
@@ -87,6 +87,7 @@ export function useThreadTerminalActions(threadRef: ScopedThreadRef | null) {
87
readonly terminalId?: string;
88
readonly location?: TerminalLaunchLocation | null;
89
readonly extraEnv?: Record<string, string>;
90
+ readonly stopOnSettle?: boolean;
91
readonly size?: { readonly cols: number; readonly rows: number };
92
}) => {
93
if (!threadRef || !canWrite() || !project) return null;
@@ -107,6 +108,7 @@ export function useThreadTerminalActions(threadRef: ScopedThreadRef | null) {
108
...(input.extraEnv ? { extraEnv: input.extraEnv } : {}),
109
}),
110
...input.size,
111
+ ...(input.stopOnSettle !== undefined ? { stopOnSettle: input.stopOnSettle } : {}),
112
},
113
});
114
return { terminalId, result };
apps/web/src/projectScripts.ts
+2
@@ -14,6 +14,7 @@ export interface ProjectScriptInput {
14
readonly runOnWorktreeCreate: ProjectScript["runOnWorktreeCreate"];
15
readonly waitForSetup: boolean;
16
readonly runOnSettle: boolean;
17
+ readonly stopOnSettle?: boolean;
18
readonly previewUrl: Exclude<ProjectScript["previewUrl"], undefined> | null;
19
readonly autoOpenPreview: boolean;
20
}
@@ -27,6 +28,7 @@ export function buildProjectScript(id: string, input: ProjectScriptInput): Proje
28
runOnWorktreeCreate: input.runOnWorktreeCreate,
29
...(input.runOnWorktreeCreate && input.waitForSetup ? { async: false } : {}),
30
...(input.runOnSettle ? { runOnSettle: true } : {}),
31
+ ...(input.stopOnSettle ? { stopOnSettle: true } : {}),
32
...(input.previewUrl === null
33
? {}
34
: {
docs/operations/development.md
+5
@@ -57,6 +57,11 @@ See the [mobile README](../../apps/mobile/README.md) for native builds and Metro
57
Flags go directly after the task name, for example `vp run dev --home-dir /tmp/t3code-dev`.
58
Add `--browser` to open a browser automatically.
59
60
+To stop a worktree's dev stack when its thread settles, import the **Dev** action from
61
+`t3.json` in Settings > Projects > Actions and start it through the action menu or its
62
+keybinding. Its `stopOnSettle` option lets T3 stop the terminal and its child processes.
63
+Running `vp run dev` through an agent's own shell tool does not attach it to this lifecycle.
64
+
65
### State and ports
66
67
Linked worktrees default to their own `.t3/userdata`, even when `T3CODE_HOME` is set.
docs/user/thread-sidebar.md
+5
-1
@@ -167,7 +167,11 @@ and prevents automatic settlement until new activity resumes the usual rules.
167
Manually settling an idle thread dismisses unanswered async questions without
168
sending an answer or restarting the agent. Settling also closes the thread's
169
terminals that wait at an idle prompt, and keeps their output. A terminal that
170
-runs a command, such as a dev server, stays open.
170
+runs a command, such as a dev server, stays open unless its action has **Stop this action
171
+when the thread settles** enabled in Settings > Projects > Actions. You can also set
172
+`"stopOnSettle": true` on a `t3.json` action and import it there. Start the command through
173
+that action so T3 can stop its terminal and child processes. Commands started through an
174
+agent's own shell tools are managed by the provider.
175
176
To reclaim disk space from settled work, turn on **Run in the thread's worktree when the
177
thread settles** for one of the project's actions, or set `"runOnSettle": true` on a
packages/contracts/src/project.ts
+1
@@ -38,6 +38,7 @@ export const ProjectScript = Schema.Struct({
38
icon: ProjectScriptIcon,
39
runOnWorktreeCreate: Schema.Boolean,
40
runOnSettle: Schema.optional(Schema.Boolean),
41
+ stopOnSettle: Schema.optional(Schema.Boolean),
42
async: Schema.optional(Schema.Boolean),
43
previewUrl: Schema.optional(TrimmedNonEmptyString),
44
autoOpenPreview: Schema.optional(Schema.Boolean),
packages/contracts/src/t3ProjectFile.ts
+6
@@ -46,6 +46,12 @@ export const T3ProjectFileScript = Schema.Struct({
46
"When true, the script runs in the thread's worktree each time the thread settles, for example to delete build output. Threads without their own worktree skip it.",
47
}),
48
),
49
+ stopOnSettle: Schema.optionalKey(
50
+ Schema.Boolean.annotate({
51
+ description:
52
+ "When true, T3 stops this action's terminal and child processes when its thread settles.",
53
+ }),
54
+ ),
55
async: Schema.optionalKey(
56
Schema.Boolean.annotate({
57
description:
packages/contracts/src/terminal.ts
+2
@@ -41,6 +41,7 @@ export const TerminalOpenInput = Schema.Struct({
41
rows: Schema.optional(TerminalRowsSchema),
42
env: Schema.optional(TerminalEnvSchema),
43
providerInstanceId: Schema.optional(ProviderInstanceId),
44
+ stopOnSettle: Schema.optional(Schema.Boolean),
45
});
46
export type TerminalOpenInput = typeof TerminalOpenInput.Type;
47
@@ -52,6 +53,7 @@ export const TerminalAttachInput = Schema.Struct({
53
rows: Schema.optional(TerminalRowsSchema),
54
env: Schema.optional(TerminalEnvSchema),
55
providerInstanceId: Schema.optional(ProviderInstanceId),
56
+ stopOnSettle: Schema.optional(Schema.Boolean),
57
restartIfNotRunning: Schema.optional(Schema.Boolean),
58
// Resubscriptions preserve stopped terminals; unknown IDs recover after a server restart.
59
resume: Schema.optional(Schema.Boolean),
packages/shared/src/t3ProjectFile.test.ts
+2
-2
@@ -11,12 +11,12 @@ describe("T3ProjectFileFromJson", () => {
11
// team scripts
12
"iconPath": "assets/logo.svg",
13
"scripts": [
14
- { "name": "Dev", "command": "pnpm dev", },
14
+ { "name": "Dev", "command": "pnpm dev", "stopOnSettle": true, },
15
],
16
}`);
17
18
expect(decoded.iconPath).toBe("assets/logo.svg");
19
- expect(decoded.scripts?.[0]).toEqual({ name: "Dev", command: "pnpm dev" });
19
+ expect(decoded.scripts?.[0]).toEqual({ name: "Dev", command: "pnpm dev", stopOnSettle: true });
20
});
21
});
22
t3.json
+6
@@ -2,6 +2,12 @@
2
"$schema": "https://t3.codes/schema/t3.json",
3
"iconPath": "assets/dev/blueprint-web-apple-touch-180.png",
4
"scripts": [
5
+ {
6
+ "name": "Dev",
7
+ "command": "vp run dev",
8
+ "icon": "play",
9
+ "stopOnSettle": true
10
+ },
11
{
12
"name": "Setup Worktree",
13
"command": "node scripts/setup-worktree.ts",