@devries-cameron20 / t3code Mirror · read-only / commits / dd059b40bc
Fork 0

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",