letagents 0.12.8 → 0.12.9

package/dist/mcp/__tests__/config-reader.test.js

@@ -0,0 +1,93 @@
+import { findLetagentsConfig, getRoomFromConfig } from "../config-reader";
+import { mkdirSync, writeFileSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+// Helper to create temp directories with config files
+function createTempDir() {
+    const dir = join(tmpdir(), `letagents-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+function cleanup(dir) {
+    try {
+        rmSync(dir, { recursive: true, force: true });
+    }
+    catch {
+        // ignore cleanup errors
+    }
+}
+describe("findLetagentsConfig", () => {
+    let tempDir;
+    afterEach(() => {
+        if (tempDir)
+            cleanup(tempDir);
+    });
+    it("returns config when .letagents.json is in the start directory", () => {
+        tempDir = createTempDir();
+        writeFileSync(join(tempDir, ".letagents.json"), JSON.stringify({ room: "github.com/EmmyMay/letagents" }));
+        const config = findLetagentsConfig(tempDir);
+        expect(config).toEqual({ room: "github.com/EmmyMay/letagents" });
+    });
+    it("walks up to find config in parent directory", () => {
+        tempDir = createTempDir();
+        const childDir = join(tempDir, "src", "mcp");
+        mkdirSync(childDir, { recursive: true });
+        writeFileSync(join(tempDir, ".letagents.json"), JSON.stringify({ room: "gitlab.com/team/project" }));
+        const config = findLetagentsConfig(childDir);
+        expect(config).toEqual({ room: "gitlab.com/team/project" });
+    });
+    it("returns null when no config file exists", () => {
+        tempDir = createTempDir();
+        const config = findLetagentsConfig(tempDir);
+        expect(config).toBeNull();
+    });
+    it("returns null for config with missing room field", () => {
+        tempDir = createTempDir();
+        writeFileSync(join(tempDir, ".letagents.json"), JSON.stringify({ version: "1.0" }));
+        // Suppress console.error for this test
+        const spy = jest.spyOn(console, "error").mockImplementation();
+        const config = findLetagentsConfig(tempDir);
+        expect(config).toBeNull();
+        spy.mockRestore();
+    });
+    it("returns null for config with empty room field", () => {
+        tempDir = createTempDir();
+        writeFileSync(join(tempDir, ".letagents.json"), JSON.stringify({ room: "" }));
+        const spy = jest.spyOn(console, "error").mockImplementation();
+        const config = findLetagentsConfig(tempDir);
+        expect(config).toBeNull();
+        spy.mockRestore();
+    });
+    it("returns null for invalid JSON", () => {
+        tempDir = createTempDir();
+        writeFileSync(join(tempDir, ".letagents.json"), "not valid json {{{");
+        const spy = jest.spyOn(console, "error").mockImplementation();
+        const config = findLetagentsConfig(tempDir);
+        expect(config).toBeNull();
+        spy.mockRestore();
+    });
+    it("trims whitespace from room name", () => {
+        tempDir = createTempDir();
+        writeFileSync(join(tempDir, ".letagents.json"), JSON.stringify({ room: "  github.com/EmmyMay/letagents  " }));
+        const config = findLetagentsConfig(tempDir);
+        expect(config).toEqual({ room: "github.com/EmmyMay/letagents" });
+    });
+});
+describe("getRoomFromConfig", () => {
+    let tempDir;
+    afterEach(() => {
+        if (tempDir)
+            cleanup(tempDir);
+    });
+    it("returns room string when config exists", () => {
+        tempDir = createTempDir();
+        writeFileSync(join(tempDir, ".letagents.json"), JSON.stringify({ room: "github.com/EmmyMay/letagents" }));
+        const room = getRoomFromConfig(tempDir);
+        expect(room).toBe("github.com/EmmyMay/letagents");
+    });
+    it("returns null when no config exists", () => {
+        tempDir = createTempDir();
+        const room = getRoomFromConfig(tempDir);
+        expect(room).toBeNull();
+    });
+});

package/dist/mcp/__tests__/git-remote.test.js

@@ -0,0 +1,37 @@
+import { normalizeGitRemote } from "../git-remote";
+describe("normalizeGitRemote", () => {
+    // SSH format tests
+    it("normalizes SSH git@github.com format", () => {
+        expect(normalizeGitRemote("git@github.com:EmmyMay/letagents.git")).toBe("github.com/EmmyMay/letagents");
+    });
+    it("normalizes SSH without .git suffix", () => {
+        expect(normalizeGitRemote("git@github.com:EmmyMay/letagents")).toBe("github.com/EmmyMay/letagents");
+    });
+    it("normalizes SSH with gitlab host", () => {
+        expect(normalizeGitRemote("git@gitlab.com:team/project.git")).toBe("gitlab.com/team/project");
+    });
+    // HTTPS format tests
+    it("normalizes HTTPS with .git suffix", () => {
+        expect(normalizeGitRemote("https://github.com/EmmyMay/letagents.git")).toBe("github.com/EmmyMay/letagents");
+    });
+    it("normalizes HTTPS without .git suffix", () => {
+        expect(normalizeGitRemote("https://github.com/EmmyMay/letagents")).toBe("github.com/EmmyMay/letagents");
+    });
+    it("normalizes HTTPS with trailing slash", () => {
+        expect(normalizeGitRemote("https://github.com/EmmyMay/letagents/")).toBe("github.com/EmmyMay/letagents");
+    });
+    // SSH protocol format tests
+    it("normalizes ssh:// protocol format", () => {
+        expect(normalizeGitRemote("ssh://git@gitlab.com/team/project.git")).toBe("gitlab.com/team/project");
+    });
+    // Edge cases
+    it("handles whitespace", () => {
+        expect(normalizeGitRemote("  git@github.com:EmmyMay/letagents.git  ")).toBe("github.com/EmmyMay/letagents");
+    });
+    it("handles nested paths", () => {
+        expect(normalizeGitRemote("https://gitlab.com/org/sub-group/project.git")).toBe("gitlab.com/org/sub-group/project");
+    });
+    it("handles Bitbucket SSH format", () => {
+        expect(normalizeGitRemote("git@bitbucket.org:workspace/repo.git")).toBe("bitbucket.org/workspace/repo");
+    });
+});

package/dist/mcp/__tests__/server-helpers.test.js

@@ -0,0 +1,121 @@
+/**
+ * Tests for server helper functions:
+ * - resolveGitRoot: resolves the root of a git repo from any subdirectory
+ * - findExistingConfig: walks parent dirs to find .letagents.json
+ *
+ * These helpers underpin the corrected initialize_repo tool behavior.
+ * @author Kingdavid Ehindero <kdof64squares@gmail.com>
+ */
+import { execSync } from "child_process";
+import { existsSync, mkdirSync, writeFileSync, rmSync } from "fs";
+import { join, resolve } from "path";
+import { tmpdir } from "os";
+// ---------------------------------------------------------------------------
+// Re-implement helpers here (they are not exported from server.ts yet)
+// We test the logic directly until we extract them to a shared module.
+// ---------------------------------------------------------------------------
+function resolveGitRoot(dir) {
+    try {
+        const root = execSync("git rev-parse --show-toplevel", {
+            cwd: dir,
+            stdio: ["pipe", "pipe", "pipe"],
+            encoding: "utf-8",
+        }).trim();
+        return root || null;
+    }
+    catch {
+        return null;
+    }
+}
+function findExistingConfig(startDir) {
+    const { dirname } = require("path");
+    let current = startDir;
+    while (true) {
+        if (existsSync(join(current, ".letagents.json")))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Helpers for tests
+// ---------------------------------------------------------------------------
+function makeTempGitRepo() {
+    const dir = join(tmpdir(), `letagents-test-${Date.now()}`);
+    mkdirSync(dir, { recursive: true });
+    execSync("git init", { cwd: dir, stdio: "pipe" });
+    execSync("git commit --allow-empty -m init", { cwd: dir, stdio: "pipe" });
+    return dir;
+}
+function cleanup(dir) {
+    try {
+        rmSync(dir, { recursive: true, force: true });
+    }
+    catch { /* ignore */ }
+}
+// ---------------------------------------------------------------------------
+// resolveGitRoot tests
+// ---------------------------------------------------------------------------
+describe("resolveGitRoot", () => {
+    let repoDir;
+    beforeAll(() => { repoDir = makeTempGitRepo(); });
+    afterAll(() => cleanup(repoDir));
+    it("returns the repo root when called from repo root", () => {
+        const result = resolveGitRoot(repoDir);
+        expect(result).toBe(resolve(repoDir));
+    });
+    it("returns the repo root when called from a subdirectory", () => {
+        const subDir = join(repoDir, "src", "deep", "path");
+        mkdirSync(subDir, { recursive: true });
+        const result = resolveGitRoot(subDir);
+        expect(result).toBe(resolve(repoDir));
+    });
+    it("returns null when not inside a git repo", () => {
+        const nonRepoDir = join(tmpdir(), `no-git-${Date.now()}`);
+        mkdirSync(nonRepoDir, { recursive: true });
+        const result = resolveGitRoot(nonRepoDir);
+        cleanup(nonRepoDir);
+        expect(result).toBeNull();
+    });
+    it("returns null for a non-existent directory", () => {
+        const result = resolveGitRoot(join(tmpdir(), "does-not-exist-12345"));
+        expect(result).toBeNull();
+    });
+});
+// ---------------------------------------------------------------------------
+// findExistingConfig tests
+// ---------------------------------------------------------------------------
+describe("findExistingConfig", () => {
+    let tempDir;
+    beforeEach(() => {
+        tempDir = join(tmpdir(), `letagents-cfg-test-${Date.now()}`);
+        mkdirSync(tempDir, { recursive: true });
+    });
+    afterEach(() => cleanup(tempDir));
+    it("returns null when no .letagents.json exists anywhere", () => {
+        const subDir = join(tempDir, "a", "b", "c");
+        mkdirSync(subDir, { recursive: true });
+        expect(findExistingConfig(subDir)).toBeNull();
+    });
+    it("finds config in the start directory", () => {
+        writeFileSync(join(tempDir, ".letagents.json"), JSON.stringify({ room: "test" }));
+        expect(findExistingConfig(tempDir)).toBe(tempDir);
+    });
+    it("finds config in a parent directory when called from subdirectory", () => {
+        const subDir = join(tempDir, "nested", "path");
+        mkdirSync(subDir, { recursive: true });
+        writeFileSync(join(tempDir, ".letagents.json"), JSON.stringify({ room: "test" }));
+        expect(findExistingConfig(subDir)).toBe(tempDir);
+    });
+    it("returns the closest config when multiple exist in the tree", () => {
+        const subDir = join(tempDir, "nested");
+        mkdirSync(subDir, { recursive: true });
+        // Config at root and at nested level — should find nested first
+        writeFileSync(join(tempDir, ".letagents.json"), JSON.stringify({ room: "root" }));
+        writeFileSync(join(subDir, ".letagents.json"), JSON.stringify({ room: "nested" }));
+        expect(findExistingConfig(subDir)).toBe(subDir);
+    });
+});

package/dist/mcp/codex-session.js

@@ -1,10 +1,14 @@
 import { randomUUID } from "crypto";
 import { spawn } from "child_process";
+import { createServer } from "net";
 import { resolve } from "path";
 import { getCurrentCodexLiveSession, getStoredCodexLiveSession, saveCodexLiveSession, updateCodexLiveSession, } from "./local-state.js";
-const DEFAULT_SERVER_URL = "ws://127.0.0.1:8765";
+const DEFAULT_SERVER_HOST = "127.0.0.1";
 const DEFAULT_STOP_PHRASE = "/stop-codex-room";
 const DEFAULT_TIMEOUT_MS = 15_000;
+const DEFAULT_STARTUP_OBSERVATION_MS = 8_000;
+const STARTUP_POLL_INTERVAL_MS = 500;
+const SESSION_MONITOR_INTERVAL_MS = 30_000;
 function getWebSocketCtor() {
     const ctor = globalThis.WebSocket;
     if (!ctor) {
@@ -14,19 +18,36 @@ function getWebSocketCtor() {
 }
 /** Track spawned server PIDs for cleanup on process exit. */
 const spawnedServerPids = new Set();
+const sessionMonitorTimers = new Map();
+function terminateSpawnedProcess(pid) {
+    try {
+        if (process.platform !== "win32") {
+            process.kill(-pid, "SIGTERM");
+            return;
+        }
+    }
+    catch {
+        // Fall back to the direct process below.
+    }
+    try {
+        process.kill(pid, "SIGTERM");
+    }
+    catch {
+        // Already gone.
+    }
+}
 let cleanupRegistered = false;
 function registerProcessCleanup() {
     if (cleanupRegistered)
         return;
     cleanupRegistered = true;
     const cleanup = () => {
+        for (const timer of sessionMonitorTimers.values()) {
+            clearInterval(timer);
+        }
+        sessionMonitorTimers.clear();
         for (const pid of spawnedServerPids) {
-            try {
-                process.kill(pid, "SIGTERM");
-            }
-            catch {
-                // Already dead — ignore.
-            }
+            terminateSpawnedProcess(pid);
         }
         spawnedServerPids.clear();
     };
@@ -136,6 +157,37 @@ async function waitForServer(serverUrl, timeoutMs = DEFAULT_TIMEOUT_MS) {
     }
     return false;
 }
+async function allocateLoopbackServerUrl() {
+    const server = createServer();
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, DEFAULT_SERVER_HOST, () => resolve());
+    });
+    const address = server.address();
+    await new Promise((resolve, reject) => {
+        server.close((error) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve();
+        });
+    });
+    if (!address || typeof address === "string") {
+        throw new Error("Unable to allocate a loopback Codex app-server port.");
+    }
+    return `ws://${DEFAULT_SERVER_HOST}:${address.port}`;
+}
+async function resolveCodexServerUrl(explicitServerUrl) {
+    if (explicitServerUrl) {
+        return explicitServerUrl;
+    }
+    const configuredServerUrl = process.env.LETAGENTS_CODEX_SERVER_URL?.trim();
+    if (configuredServerUrl) {
+        return configuredServerUrl;
+    }
+    return allocateLoopbackServerUrl();
+}
 function launchAppServer(serverUrl, codexBin) {
     const child = spawn(codexBin, ["app-server", "--listen", serverUrl], {
         detached: true,
@@ -173,14 +225,16 @@ function buildStartPrompt(input) {
         "",
         "Instructions:",
         `1. ${buildJoinInstruction(input.joined_via, input.room_identifier)}`,
-        "2. Do not start another live session. Join the room inline in this worker only.",
-        "3. Read the room and task board before contributing so you have current context.",
-        "4. Keep polling with wait_for_messages using a 30000 ms timeout and track the latest seen message id.",
-        "5. When new messages arrive, contribute when useful. Be concise, thoughtful, and non-repetitive.",
-        "6. When the room asks for coding work, do the work locally in this repository: inspect files, edit code, run checks, commit when asked, and push only when explicitly requested.",
-        "7. Post short status updates to the room when you start meaningful work, when you are blocked, and when you finish meaningful work.",
-        `8. Stop immediately if a browser/user room message text exactly equals: ${input.stop_phrase}`,
-        `9. When stopping, reply in this thread with exactly: ${input.token}_DONE`,
+        "2. Call register_agent_session with session_kind=\"worker\" and runtime=\"codex\". Keep the returned agent_session_id.",
+        "3. Pass that agent_session_id to wait_for_messages, send_message, post_status, and task tools whenever the tool accepts it.",
+        "4. Do not start another live session. Join the room inline in this worker only.",
+        "5. Read the room and task board before contributing so you have current context.",
+        "6. Keep polling with wait_for_messages using a 30000 ms timeout and track the latest seen message id.",
+        "7. When new messages arrive, contribute when useful. Be concise, thoughtful, and non-repetitive.",
+        "8. When the room asks for coding work, do the work locally in this repository: inspect files, edit code, run checks, commit when asked, and push only when explicitly requested.",
+        "9. Post short status updates to the room when you start meaningful work, when you are blocked, and when you finish meaningful work.",
+        `10. Stop immediately if a browser/user room message text exactly equals: ${input.stop_phrase}`,
+        `11. When stopping, reply in this thread with exactly: ${input.token}_DONE`,
         "",
         "Constraints:",
         "- Do not narrate hidden chain-of-thought.",
@@ -223,7 +277,10 @@ function summarizeItems(items) {
         return { type: item.type ?? "unknown" };
     });
 }
-function mapSessionStatus(session, serverReachable, threadStatus, turnStatus) {
+export function deriveCodexLiveSessionStatus(session, serverReachable, threadStatus, turnStatus) {
+    if (threadStatus === "systemError" || threadStatus === "error" || turnStatus === "failed") {
+        return "failed";
+    }
     if (turnStatus === "completed") {
         return "completed";
     }
@@ -243,6 +300,96 @@ function mapSessionStatus(session, serverReachable, threadStatus, turnStatus) {
     }
     return session.status;
 }
+function isTerminalCodexSessionStatus(status) {
+    return status === "completed" || status === "interrupted" || status === "failed";
+}
+function parseStartupObservationMs() {
+    const parsed = Number.parseInt(process.env.LETAGENTS_CODEX_STARTUP_OBSERVATION_MS ?? "", 10);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        return DEFAULT_STARTUP_OBSERVATION_MS;
+    }
+    return parsed;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function clearSessionMonitor(sessionId) {
+    const timer = sessionMonitorTimers.get(sessionId);
+    if (!timer) {
+        return;
+    }
+    clearInterval(timer);
+    sessionMonitorTimers.delete(sessionId);
+}
+function killOwnedAppServer(session) {
+    if (!session.launched_server || !session.server_pid) {
+        return;
+    }
+    terminateSpawnedProcess(session.server_pid);
+    spawnedServerPids.delete(session.server_pid);
+}
+function scheduleOwnedSessionMonitor(session) {
+    if (!session.launched_server || sessionMonitorTimers.has(session.session_id)) {
+        return;
+    }
+    const timer = setInterval(() => {
+        void inspectLocalCodexSession(session.session_id)
+            .then((status) => {
+            if (!status ||
+                !status.server_reachable ||
+                isTerminalCodexSessionStatus(status.session.status)) {
+                clearSessionMonitor(session.session_id);
+            }
+        })
+            .catch(() => {
+            const latest = getStoredCodexLiveSession(session.session_id);
+            if (latest?.launched_server) {
+                killOwnedAppServer(latest);
+            }
+            clearSessionMonitor(session.session_id);
+        });
+    }, SESSION_MONITOR_INTERVAL_MS);
+    timer.unref?.();
+    sessionMonitorTimers.set(session.session_id, timer);
+}
+async function waitForWorkerStartup(session) {
+    const observationMs = parseStartupObservationMs();
+    const deadline = Date.now() + observationMs;
+    let latest = session;
+    while (Date.now() < deadline) {
+        await sleep(Math.min(STARTUP_POLL_INTERVAL_MS, Math.max(deadline - Date.now(), 0)));
+        const inspected = await inspectLocalCodexSession(session.session_id);
+        if (!inspected) {
+            continue;
+        }
+        latest = inspected.session;
+        if (!inspected.server_reachable || latest.status === "unknown") {
+            const reason = !inspected.server_reachable
+                ? "app-server became unreachable during startup"
+                : "worker status became unknown during startup";
+            const failed = updateCodexLiveSession(session.session_id, (current) => ({
+                ...current,
+                status: "failed",
+                last_error: reason,
+                updated_at: new Date().toISOString(),
+            })) ?? latest;
+            throw new Error(`Codex worker exited during startup: ${failed.last_error ?? reason}`);
+        }
+        if (isTerminalCodexSessionStatus(latest.status)) {
+            const reason = latest.status === "completed"
+                ? "turn completed before entering the room polling loop"
+                : `turn entered ${latest.status}`;
+            const failed = updateCodexLiveSession(session.session_id, (current) => ({
+                ...current,
+                status: "failed",
+                last_error: reason,
+                updated_at: new Date().toISOString(),
+            })) ?? latest;
+            throw new Error(`Codex worker exited during startup: ${failed.last_error ?? reason}`);
+        }
+    }
+    return latest;
+}
 function toSessionState(input) {
     const now = new Date().toISOString();
     return {
@@ -306,9 +453,13 @@ export async function inspectLocalCodexSession(sessionId, roomId) {
     if (!serverReachable) {
         const updated = updateCodexLiveSession(session.session_id, (current) => ({
             ...current,
-            status: mapSessionStatus(current, false, null, null),
+            status: deriveCodexLiveSessionStatus(current, false, null, null),
             updated_at: new Date().toISOString(),
         })) ?? session;
+        if (updated.launched_server) {
+            killOwnedAppServer(updated);
+            clearSessionMonitor(updated.session_id);
+        }
         return {
             session: updated,
             server_reachable: false,
@@ -318,8 +469,8 @@ export async function inspectLocalCodexSession(sessionId, roomId) {
         };
     }
     const client = new RpcClient(session.server_url);
-    await client.connect();
     try {
+        await client.connect();
         let read = null;
         try {
             read = await client.request("thread/read", {
@@ -338,10 +489,14 @@ export async function inspectLocalCodexSession(sessionId, roomId) {
         const turnStatus = extractTurnStatus(turn);
         const updated = updateCodexLiveSession(session.session_id, (current) => ({
             ...current,
-            status: mapSessionStatus(current, true, threadStatus, turnStatus),
+            status: deriveCodexLiveSessionStatus(current, true, threadStatus, turnStatus),
             last_error: null,
             updated_at: new Date().toISOString(),
         })) ?? session;
+        if (isTerminalCodexSessionStatus(updated.status)) {
+            killOwnedAppServer(updated);
+            clearSessionMonitor(updated.session_id);
+        }
         return {
             session: updated,
             server_reachable: true,
@@ -357,6 +512,10 @@ export async function inspectLocalCodexSession(sessionId, roomId) {
             last_error: error instanceof Error ? error.message : String(error),
             updated_at: new Date().toISOString(),
         })) ?? session;
+        if (updated.launched_server) {
+            killOwnedAppServer(updated);
+            clearSessionMonitor(updated.session_id);
+        }
         return {
             session: updated,
             server_reachable: true,
@@ -378,10 +537,11 @@ export async function startLocalCodexSession(input) {
         const inspected = await inspectLocalCodexSession(currentSession.session_id);
         if (inspected &&
             (inspected.session.status === "running" || inspected.session.status === "starting")) {
+            scheduleOwnedSessionMonitor(inspected.session);
             return { session: inspected.session, reused: true };
         }
     }
-    const serverUrl = input.server_url || DEFAULT_SERVER_URL;
+    const serverUrl = await resolveCodexServerUrl(input.server_url);
     const stopPhrase = input.stop_phrase || DEFAULT_STOP_PHRASE;
     const maxMinutes = Number.isFinite(input.max_minutes) ? Math.max(0, input.max_minutes ?? 0) : 0;
     const codexBin = input.codex_bin || process.env.LETAGENTS_CODEX_BIN || "codex";
@@ -389,20 +549,22 @@ export async function startLocalCodexSession(input) {
     const deadline = formatDeadline(maxMinutes);
     const launchedServer = !(await isServerReady(serverUrl));
     let serverPid = null;
-    if (launchedServer) {
-        serverPid = launchAppServer(serverUrl, codexBin);
-        if (serverPid) {
-            spawnedServerPids.add(serverPid);
-            registerProcessCleanup();
-        }
-        const ready = await waitForServer(serverUrl);
-        if (!ready) {
-            throw new Error(`Timed out waiting for codex app-server at ${serverUrl}`);
-        }
-    }
-    const client = new RpcClient(serverUrl);
-    await client.connect();
+    let client = null;
+    let startupSucceeded = false;
     try {
+        if (launchedServer) {
+            serverPid = launchAppServer(serverUrl, codexBin);
+            if (serverPid) {
+                spawnedServerPids.add(serverPid);
+                registerProcessCleanup();
+            }
+            const ready = await waitForServer(serverUrl);
+            if (!ready) {
+                throw new Error(`Timed out waiting for codex app-server at ${serverUrl}`);
+            }
+        }
+        client = new RpcClient(serverUrl);
+        await client.connect();
         const threadStart = await client.request("thread/start", {});
         const threadId = threadStart.thread?.id;
         if (!threadId) {
@@ -447,10 +609,26 @@ export async function startLocalCodexSession(input) {
             launched_server: launchedServer,
             codex_bin: codexBin,
         }));
-        return { session, reused: false };
+        try {
+            const verifiedSession = await waitForWorkerStartup(session);
+            scheduleOwnedSessionMonitor(verifiedSession);
+            startupSucceeded = true;
+            return { session: verifiedSession, reused: false };
+        }
+        catch (error) {
+            killOwnedAppServer(session);
+            throw error;
+        }
+    }
+    catch (error) {
+        if (!startupSucceeded && launchedServer && serverPid) {
+            terminateSpawnedProcess(serverPid);
+            spawnedServerPids.delete(serverPid);
+        }
+        throw error;
     }
     finally {
-        client.close();
+        client?.close();
     }
 }
 export async function stopLocalCodexSession(options) {
@@ -486,15 +664,9 @@ export async function stopLocalCodexSession(options) {
         last_error: serverReachable ? null : "server unreachable at stop time",
         updated_at: new Date().toISOString(),
     })) ?? session;
-    if (options?.shutdown_server && updated.server_pid) {
-        try {
-            process.kill(updated.server_pid, "SIGTERM");
-            spawnedServerPids.delete(updated.server_pid);
-        }
-        catch {
-            // Process already dead — ignore.
-            spawnedServerPids.delete(updated.server_pid);
-        }
+    if (options?.shutdown_server || updated.launched_server) {
+        killOwnedAppServer(updated);
     }
+    clearSessionMonitor(updated.session_id);
     return updated;
 }