fix(terminal): polish pass — node-pty diagnostics, Ctrl+W guards, black flash, split grouping

apps/desktop/src/window/DesktopWindow.ts

@@ -514,6 +514,19 @@ export const make = Effect.gen(function* () {
       }
     });
 
+    // Electron's windowMenu close role owns CmdOrCtrl+W. Holding the
+    // close-terminal shortcut auto-repeats faster than the renderer can re-arm
+    // its guard after the last terminal closes, and a single leaked repeat
+    // closes the whole window (and on Windows/Linux, the app). Only deliberate,
+    // non-repeated presses may act.
+    window.webContents.on("before-input-event", (event, input) => {
+      if (input.type !== "keyDown" || !input.isAutoRepeat) return;
+      const modifier = environment.platform === "darwin" ? input.meta : input.control;
+      if (modifier && !input.alt && !input.shift && input.key.toLowerCase() === "w") {
+        event.preventDefault();
+      }
+    });
+
     window.on("page-title-updated", (event) => {
       event.preventDefault();
       window.setTitle(environment.displayName);

apps/server/src/cli/server.ts

@@ -5,6 +5,25 @@ import { ServerConfig, type StartupPresentation } from "../config.ts";
 import { runServer } from "../server.ts";
 import { type CliServerFlags, resolveServerConfig, sharedServerCommandFlags } from "./config.ts";
 
+/**
+ * Defects thrown while building the server layer can be swallowed by headless
+ * startup logging, which used to make `npx t3` exit cleanly with no output on a
+ * broken install. The entrypoint owns process-exit policy, so render whatever
+ * diagnosis the defect carries and make sure the exit code is non-zero.
+ */
+const hasDiagnostic = (defect: unknown): defect is { readonly diagnostic: string } =>
+  typeof defect === "object" &&
+  defect !== null &&
+  typeof (defect as { diagnostic?: unknown }).diagnostic === "string";
+
+const reportStartupDefect = (defect: unknown) =>
+  Effect.sync(() => {
+    process.exitCode = 1;
+    if (hasDiagnostic(defect)) {
+      process.stderr.write(`${defect.diagnostic}\n`);
+    }
+  });
+
 export const runServerCommand = (
   flags: CliServerFlags,
   options?: {
@@ -15,7 +34,10 @@ export const runServerCommand = (
   Effect.gen(function* () {
     const logLevel = yield* GlobalFlag.LogLevel;
     const config = yield* resolveServerConfig(flags, logLevel, options);
-    return yield* runServer.pipe(Effect.provideService(ServerConfig, config));
+    return yield* runServer.pipe(
+      Effect.provideService(ServerConfig, config),
+      Effect.tapDefect(reportStartupDefect),
+    );
   });
 
 export const startCommand = Command.make("start", { ...sharedServerCommandFlags }).pipe(

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

@@ -1260,6 +1260,29 @@ it.layer(
     }),
   );
 
+  it.effect("does not retry other shells when spawn-helper is not executable", () =>
+    Effect.gen(function* () {
+      const { manager, ptyAdapter, getEvents } = yield* createManager();
+      ptyAdapter.spawnFailures.push(
+        new PtyAdapter.SpawnHelperNotExecutableError({
+          helperPath: "/pkg/spawn-helper",
+          cause: new Error("posix_spawnp failed."),
+        }),
+      );
+
+      const snapshot = yield* manager.open(openInput());
+
+      assert.equal(snapshot.status, "error");
+      expect(ptyAdapter.spawnInputs).toHaveLength(1);
+
+      // The user must see the fix, not the generic "tried these shells" wrapper.
+      const events = yield* getEvents;
+      const errorEvent = events.find((event) => event.type === "error");
+      assert.isDefined(errorEvent);
+      assert.include(errorEvent?.message ?? "", 'chmod +x "/pkg/spawn-helper"');
+    }),
+  );
+
   it.effect("prefers PowerShell over ComSpec for Windows terminals", () =>
     Effect.gen(function* () {
       const { manager, ptyAdapter } = yield* createManager(5, {

apps/server/src/terminal/Manager.ts

@@ -565,6 +565,12 @@ function resolveShellCandidates(
 }
 
 function isRetryableShellSpawnError(error: PtyAdapter.PtySpawnError): boolean {
+  // A non-executable node-pty spawn-helper fails identically for every shell;
+  // retrying candidates would only bury the actionable error under fallbacks.
+  if (PtyAdapter.hasSpawnHelperNotExecutableCause(error)) {
+    return false;
+  }
+
   const queue: unknown[] = [error];
   const seen = new Set<unknown>();
   const messages: string[] = [];
@@ -1959,7 +1965,10 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
 
       yield* evictInactiveSessionsIfNeeded();
 
-      const message = error.message;
+      // The outer spawn error only says which shells were tried. When the real
+      // culprit is diagnosed further down the chain, publish that instead so the
+      // user sees the fix rather than a generic failure.
+      const message = (PtyAdapter.findSpawnHelperNotExecutableCause(error) ?? error).message;
       yield* publishEvent({
         type: "error",
         threadId: session.threadId,

apps/server/src/terminal/NodePtyAdapter.test.ts

@@ -75,6 +75,11 @@ it.effect("reports native module load failures as structured startup defects", (
         architecture: "x64",
       });
       assert.equal(error.message, "Failed to load node-pty for win32-x64.");
+      // The CLI entrypoint renders this; a broken install must never exit
+      // cleanly with no output.
+      assert.include(error.diagnostic, "Failed to load node-pty for win32-x64.");
+      assert.include(error.diagnostic, "native binding could not be loaded");
+      assert.include(error.diagnostic, "reinstall t3");
     }
   }).pipe(
     Effect.provide(
@@ -86,3 +91,157 @@ it.effect("reports native module load failures as structured startup defects", (
     ),
   ),
 );
+
+it("resolves helper executability against the calling process, not any exec bit", () => {
+  const owned = { ownerUid: 501, ownerGid: 20 };
+
+  // Owner-only binary: executable for its owner, not for anyone else.
+  assert.isTrue(
+    NodePtyAdapter.modeIsExecutableFor({
+      mode: 0o100,
+      ...owned,
+      processUid: 501,
+      processGids: [20],
+    }),
+  );
+  assert.isFalse(
+    NodePtyAdapter.modeIsExecutableFor({
+      mode: 0o100,
+      ...owned,
+      processUid: 502,
+      processGids: [21],
+    }),
+  );
+
+  // Group and other bits are honoured independently of the owner bit.
+  assert.isTrue(
+    NodePtyAdapter.modeIsExecutableFor({
+      mode: 0o010,
+      ...owned,
+      processUid: 502,
+      processGids: [20],
+    }),
+  );
+  assert.isFalse(
+    NodePtyAdapter.modeIsExecutableFor({
+      mode: 0o600,
+      ...owned,
+      processUid: 501,
+      processGids: [20],
+    }),
+  );
+  assert.isTrue(
+    NodePtyAdapter.modeIsExecutableFor({
+      mode: 0o001,
+      ...owned,
+      processUid: 502,
+      processGids: [21],
+    }),
+  );
+
+  // Root and unknown identities fall back to "somebody can execute this".
+  assert.isTrue(
+    NodePtyAdapter.modeIsExecutableFor({ mode: 0o100, ...owned, processUid: 0, processGids: [0] }),
+  );
+  assert.isFalse(
+    NodePtyAdapter.modeIsExecutableFor({ mode: 0o644, ...owned, processUid: 0, processGids: [0] }),
+  );
+  assert.isTrue(
+    NodePtyAdapter.modeIsExecutableFor({
+      mode: 0o100,
+      ownerUid: null,
+      ownerGid: null,
+      processUid: null,
+      processGids: [],
+    }),
+  );
+
+  // The reported bug: a 0644 helper is never executable for anyone.
+  assert.isFalse(
+    NodePtyAdapter.modeIsExecutableFor({
+      mode: 0o644,
+      ...owned,
+      processUid: 501,
+      processGids: [20],
+    }),
+  );
+});
+
+it("leaves non-posix_spawnp failures untouched", () => {
+  const cause = new Error("cwd does not exist");
+  const described = NodePtyAdapter.describeSpawnFailure({
+    cause,
+    platform: "darwin",
+    helperPath: "/pkg/node-pty/build/Release/spawn-helper",
+    helperIsExecutable: false,
+  });
+  assert.equal(described, cause);
+});
+
+it("explains posix_spawnp failures caused by a non-executable spawn-helper", () => {
+  const cause = new Error("posix_spawnp failed.");
+  const described = NodePtyAdapter.describeSpawnFailure({
+    cause,
+    platform: "darwin",
+    helperPath: "/pkg/node-pty/build/Release/spawn-helper",
+    helperIsExecutable: false,
+  });
+  assert.instanceOf(described, PtyAdapter.SpawnHelperNotExecutableError);
+  const error = described as PtyAdapter.SpawnHelperNotExecutableError;
+  assert.equal(error.helperPath, "/pkg/node-pty/build/Release/spawn-helper");
+  assert.include(error.message, 'chmod +x "/pkg/node-pty/build/Release/spawn-helper"');
+  assert.equal(error.cause, cause);
+  // The terminal manager keys its retry decision off the tag, not the wording.
+  assert.isTrue(PtyAdapter.hasSpawnHelperNotExecutableCause(error));
+  assert.isTrue(
+    PtyAdapter.hasSpawnHelperNotExecutableCause(
+      new PtyAdapter.PtySpawnError({ adapter: "node-pty", shell: "/bin/zsh", cause: error }),
+    ),
+  );
+  assert.isFalse(PtyAdapter.hasSpawnHelperNotExecutableCause(cause));
+});
+
+it("keeps posix_spawnp failures as-is when the helper is executable or missing", () => {
+  const cause = new Error("posix_spawnp failed.");
+  assert.equal(
+    NodePtyAdapter.describeSpawnFailure({
+      cause,
+      platform: "darwin",
+      helperPath: "/pkg/node-pty/build/Release/spawn-helper",
+      helperIsExecutable: true,
+    }),
+    cause,
+  );
+  assert.equal(
+    NodePtyAdapter.describeSpawnFailure({
+      cause,
+      platform: "darwin",
+      helperPath: null,
+      helperIsExecutable: false,
+    }),
+    cause,
+  );
+  assert.equal(
+    NodePtyAdapter.describeSpawnFailure({
+      cause,
+      platform: "win32",
+      helperPath: "/pkg/node-pty/build/Release/spawn-helper",
+      helperIsExecutable: false,
+    }),
+    cause,
+  );
+});
+
+it("finds posix_spawnp mentions through nested error causes", () => {
+  const nested = new Error("outer wrapper", {
+    cause: new Error("posix_spawnp failed."),
+  });
+  const described = NodePtyAdapter.describeSpawnFailure({
+    cause: nested,
+    platform: "darwin",
+    helperPath: "/pkg/spawn-helper",
+    helperIsExecutable: false,
+  });
+  assert.instanceOf(described, Error);
+  assert.include((described as Error).message, "chmod +x");
+});