fix: repair stale conversation working directories (#3318)

Co-authored-by: Letta Code <noreply@letta.com>
Co-authored-by: cpacker <packercharles@gmail.com>

Author: 3 people

scripts/check-test-coverage.cjs

@@ -73,6 +73,7 @@ const ciDirs = [
   "src/cli",
   "src/cron",
   "src/experiments",
+  "src/helpers",
   "src/hooks",
   "src/lsp",
   "src/mods",

scripts/isolated-unit-tests.json

@@ -69,6 +69,21 @@
       "path": "src/websocket/listener/auth-lifecycle.test.ts",
       "timeoutMs": 30000,
       "reason": "Exercises real WebSockets while mutating listener, settings, HOME, and process environment state."
+    },
+    {
+      "path": "src/websocket/listener/control-inputs.test.ts",
+      "timeoutMs": 15000,
+      "reason": "Mutates HOME and the remote-settings singleton while exercising cwd recovery persistence."
+    },
+    {
+      "path": "src/websocket/listener/protocol-ergonomics.test.ts",
+      "timeoutMs": 15000,
+      "reason": "Mutates HOME and the remote-settings singleton while verifying durable cwd-map pruning."
+    },
+    {
+      "path": "src/websocket/listener/remote-settings.test.ts",
+      "timeoutMs": 15000,
+      "reason": "Mutates HOME and the remote-settings singleton to verify startup cwd-map repair."
     }
   ]
 }

scripts/run-unit-tests.cjs

@@ -12,6 +12,7 @@ const dirs = [
   "src/cli",
   "src/cron",
   "src/experiments",
+  "src/helpers",
   "src/hooks",
   "src/lsp",
   "src/mods",

src/cli/subcommands/listen.tsx

@@ -32,6 +32,7 @@ import {
   MissingListenerApiKeyError,
   resolveListenerRegistrationOptions,
 } from "@/websocket/listener/auth";
+import { flushRemoteSettingsWrites } from "@/websocket/listener/remote-settings";
 
 type ListenerProcessAnchor = {
   close: () => void;
@@ -269,13 +270,18 @@ export async function runListenSubcommand(argv: string[]): Promise<number> {
   await settingsManager.initialize();
   await applyStartupPermissionMode({});
   telemetry.setSurface(getListenerTelemetrySurface());
-  telemetry.init();
+  telemetry.init({ handleSigint: false });
 
   // Register signal handlers so the listener can clean up child processes
   // (subagents, bash commands, PTY sessions) before exiting. Without these,
   // SIGTERM from the desktop app only kills the listener process itself,
   // orphaning its descendants which accumulate over time.
-  const handleShutdownSignal = async (): Promise<void> => {
+  let isShuttingDown = false;
+  const handleShutdownSignal = async (
+    signal: "SIGINT" | "SIGHUP" | "SIGTERM",
+  ): Promise<void> => {
+    if (isShuttingDown) return;
+    isShuttingDown = true;
     try {
       const { stopListenerClient, isListenerActive } = await import(
         "@/websocket/listen-client"
@@ -292,11 +298,14 @@ export async function runListenSubcommand(argv: string[]): Promise<number> {
     } catch {
       // Best-effort cleanup — don't block exit
     }
+    await flushRemoteSettingsWrites();
+    await flushListenerTelemetryEnd(`listener_${signal.toLowerCase()}`);
     process.exit(0);
   };
 
-  process.once("SIGTERM", handleShutdownSignal);
-  process.once("SIGINT", handleShutdownSignal);
+  process.once("SIGTERM", () => void handleShutdownSignal("SIGTERM"));
+  process.once("SIGINT", () => void handleShutdownSignal("SIGINT"));
+  process.once("SIGHUP", () => void handleShutdownSignal("SIGHUP"));
 
   const exitWithTelemetry = async (
     code: number,
@@ -312,6 +321,7 @@ export async function runListenSubcommand(argv: string[]): Promise<number> {
     } catch {
       // Best effort — don't block exit on channel cleanup failure
     }
+    await flushRemoteSettingsWrites();
     await flushListenerTelemetryEnd(exitReason);
     process.exit(code);
   };
@@ -772,6 +782,7 @@ export async function runListenSubcommand(argv: string[]): Promise<number> {
     const msg = error instanceof Error ? error.message : String(error);
     sessionLog.log(`FATAL: ${msg}`);
     console.error(`Failed to start listener: ${msg}`);
+    await flushRemoteSettingsWrites();
     await flushListenerTelemetryEnd("listener_start_failed");
     return 1;
   }

src/helpers/usable-directory.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test";
+import {
+  getDirectoryUsability,
+  isConfirmedUnusableDirectory,
+} from "./usable-directory";
+
+describe("directory usability", () => {
+  test("classifies missing paths and regular files as confirmed unusable", () => {
+    expect(getDirectoryUsability("/missing", () => undefined)).toBe("missing");
+    expect(
+      getDirectoryUsability("/file", () => ({ isDirectory: () => false })),
+    ).toBe("not-directory");
+  });
+
+  test("preserves paths when stat fails unexpectedly", () => {
+    for (const code of ["EACCES", "EIO", "EMFILE"]) {
+      const statDirectory = () => {
+        throw Object.assign(new Error("unexpected stat failure"), { code });
+      };
+
+      expect(getDirectoryUsability("/restricted", statDirectory)).toBe(
+        "unknown",
+      );
+      expect(isConfirmedUnusableDirectory("/restricted", statDirectory)).toBe(
+        false,
+      );
+    }
+  });
+
+  test("treats thrown missing-path errors as confirmed unusable", () => {
+    for (const code of ["ENOENT", "ENOTDIR"]) {
+      const statDirectory = () => {
+        throw Object.assign(new Error("missing path"), { code });
+      };
+
+      expect(getDirectoryUsability("/missing", statDirectory)).toBe("missing");
+      expect(isConfirmedUnusableDirectory("/missing", statDirectory)).toBe(
+        true,
+      );
+    }
+  });
+});

src/helpers/usable-directory.ts

@@ -1,14 +1,48 @@
-import { statSync } from "node:fs";
+import { type Stats, statSync } from "node:fs";
 
-/** True when the path exists and is a directory. */
-export function isUsableDirectory(dirPath: string | null | undefined): boolean {
+export type DirectoryUsability =
+  | "usable"
+  | "missing"
+  | "not-directory"
+  | "unknown";
+
+type DirectoryStat = (
+  dirPath: string,
+) => Pick<Stats, "isDirectory"> | undefined;
+
+function readDirectoryStats(dirPath: string): Stats | undefined {
+  return statSync(dirPath, { throwIfNoEntry: false });
+}
+
+export function getDirectoryUsability(
+  dirPath: string | null | undefined,
+  statDirectory: DirectoryStat = readDirectoryStats,
+): DirectoryUsability {
   if (typeof dirPath !== "string" || dirPath.length === 0) {
-    return false;
+    return "missing";
   }
 
   try {
-    return statSync(dirPath, { throwIfNoEntry: false })?.isDirectory() ?? false;
-  } catch {
-    return false;
+    const stats = statDirectory(dirPath);
+    if (!stats) {
+      return "missing";
+    }
+    return stats.isDirectory() ? "usable" : "not-directory";
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException | null)?.code;
+    return code === "ENOENT" || code === "ENOTDIR" ? "missing" : "unknown";
   }
 }
+
+export function isConfirmedUnusableDirectory(
+  dirPath: string | null | undefined,
+  statDirectory?: DirectoryStat,
+): boolean {
+  const usability = getDirectoryUsability(dirPath, statDirectory);
+  return usability === "missing" || usability === "not-directory";
+}
+
+/** True when the path exists and is a directory. */
+export function isUsableDirectory(dirPath: string | null | undefined): boolean {
+  return getDirectoryUsability(dirPath) === "usable";
+}

src/runtime-context.ts

@@ -1,5 +1,5 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-import { homedir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import type { SkillSource } from "./agent/skills";
 import type { MessageChannelToolDiscoveryScope } from "./channels/message-tool";
 import type { ChannelTurnSource } from "./channels/types";
@@ -92,11 +92,12 @@ function getProcessWorkingDirectory(): string | null {
   }
 }
 
-function getFallbackWorkingDirectory(): string {
+export function getFallbackWorkingDirectory(): string {
   const fallback = [
     process.env.USER_CWD,
     getProcessWorkingDirectory(),
     homedir(),
+    tmpdir(),
     process.platform === "win32" ? undefined : "/",
   ].find(isUsableDirectory);
 

src/types/protocol_v2.ts

@@ -423,16 +423,16 @@ export interface GitContext {
   recent_branches: string[];
 }
 
-/**
- * Bottom-bar and device execution context state.
- */
+/** Bottom-bar and device execution context state. */
 export interface DeviceStatus {
   current_connection_id: string | null;
   connection_name: string | null;
   is_online: boolean;
   is_processing: boolean;
   current_permission_mode: DevicePermissionMode;
   current_working_directory: string | null;
+  /** Monotonic signal for cwd changes and rejected stale cwd requests. */
+  cwd_revision?: number;
   git_context: GitContext | null;
   letta_code_version: string | null;
   current_toolset: ToolsetName | null;

src/websocket/listener/client.ts

@@ -51,6 +51,7 @@ import {
 } from "./control-inputs";
 import { getOrCreateScopedRuntime } from "./conversation-runtime";
 import {
+  getBootWorkingDirectory,
   getConversationWorkingDirectory,
   setConversationWorkingDirectory,
 } from "./cwd";
@@ -239,7 +240,7 @@ function createLegacyTestRuntime(): ConversationRuntime & {
       },
     },
     bootWorkingDirectory: {
-      get: () => listener.bootWorkingDirectory,
+      get: () => getBootWorkingDirectory(listener),
       set: (value: string) => {
         listener.bootWorkingDirectory = value;
       },

src/websocket/listener/commands.ts

@@ -48,6 +48,7 @@ import {
   emitCanonicalMessageDelta,
   emitDeviceStatusUpdate,
 } from "./protocol-outbound";
+import { flushRemoteSettingsWrites } from "./remote-settings";
 import { clearConversationRuntimeState, emitListenerStatus } from "./runtime";
 import {
   ensureSecretsHydratedForAgent,
@@ -374,7 +375,8 @@ function scheduleRemoteRestart(
   }
 
   log(`scheduling remote listener restart for env ${connectionName}`);
-  setTimeout(() => {
+  setTimeout(async () => {
+    await flushRemoteSettingsWrites();
     log(
       `spawning replacement listener: ${process.execPath} ${entrypoint} remote --env-name ${connectionName}`,
     );