fix(desktop): explain why a second server cannot start

The server lock at <PYTHINKER_CODE_HOME>/server/lock is global rather than
per-port, so a CLI server on any port stops the desktop Host from starting.
The Host exited non-zero and the desktop reported only 'Host exited before
readiness (code 1, signal null)', which names neither the conflicting process
nor a way out.

Parse the Host's canonical conflict line and show a Retry/Quit dialog naming
the process, port and start time. Do not stop the other server: it may be
serving live sessions, and the choice belongs to the user.

Keep the single-instance rule itself. Two servers sharing one Pythinker home
would race on session state.json writes, truncate each other's wire.jsonl
rewrites, and both claim the same next sequence in the shared event journal,
so refusing to start is correct.

Also honor an error's declared exit code in 'server run': ServerLockedError
uses 2 to mark a lock conflict, which the catch-all flattened to 1.

Author: elkaix

apps/desktop/src/host-supervisor.ts

@@ -29,6 +29,30 @@ export function isPortInUseError(message: string): boolean {
   return /EADDRINUSE|address already in use/iu.test(message)
 }
 
+/** The live server described by the Host's single-instance conflict line. */
+export interface RunningServerConflict {
+  readonly pid: number
+  readonly port: number
+  readonly startedAt: string
+}
+
+/**
+ * Recognize the Host's single-instance lock conflict.
+ *
+ * The server refuses to start while another one holds the lock at
+ * `<PYTHINKER_CODE_HOME>/server/lock`, and that lock is global rather than
+ * per-port, so a CLI server on any port blocks the desktop Host. Without this
+ * the conflict surfaces only as a generic non-zero exit, which tells the user
+ * nothing about which process to stop.
+ * @param message - Host output, including the diagnostic appended on failure.
+ * @returns The conflicting server's details, or undefined for other failures.
+ */
+export function parseRunningServerConflict(message: string): RunningServerConflict | undefined {
+  const match = /server already running \(pid=(\d+), port=(\d+), started=([^)]*)\)/u.exec(message)
+  if (match === null) return undefined
+  return { pid: Number(match[1]), port: Number(match[2]), startedAt: match[3]! }
+}
+
 /** Incremental parser for the Web Host's canonical readiness line. */
 export interface ReadinessParser {
   /**

apps/desktop/src/main.ts

@@ -27,6 +27,7 @@ import {
 import {
   createHostSupervisor,
   isPortInUseError,
+  parseRunningServerConflict,
   resolveDesktopPort,
   spawnPythinkerServer,
   type HostSupervisor,
@@ -345,6 +346,22 @@ async function boot(): Promise<void> {
       } catch (error) {
         track('desktop_server_failed')
         const message = error instanceof Error ? error.message : String(error)
+
+        const conflict = parseRunningServerConflict(message)
+        if (conflict !== undefined) {
+          const conflicted = await dialog.showMessageBox({
+            type: 'error',
+            buttons: ['Retry', 'Quit'],
+            defaultId: 0,
+            cancelId: 1,
+            title: `${APP_NAME} cannot start its server`,
+            message: `Another Pythinker server is already running (process ${String(conflict.pid)} on port ${String(conflict.port)}, started ${conflict.startedAt}). Only one server can run at a time, because they would share the same session files. Stop that server, then retry.`,
+          })
+          if (conflicted.response === 0) continue
+          await requestAppQuit()
+          return
+        }
+
         if (!isPortInUseError(message)) throw error
 
         const result = await dialog.showMessageBox({

apps/desktop/tests/host-supervisor.spec.ts

@@ -139,6 +139,28 @@ describe('desktop Host port', () => {
     )).toBe(true)
     expect(hostSupervisor.isPortInUseError('desktop Host exited before readiness (code 1, signal null)')).toBe(false)
   })
+
+  it('detects output that reports a single-instance lock conflict', () => {
+    // Verbatim failure observed when a CLI server held the global lock.
+    const observed = [
+      'desktop Host exited before readiness (code 1, signal null)',
+      'Host output:',
+      'server already running (pid=78405, port=58700, started=2026-08-17T18:06:12.341Z)',
+    ].join('\n')
+
+    expect(hostSupervisor.parseRunningServerConflict(observed)).toEqual({
+      pid: 78_405,
+      port: 58_700,
+      startedAt: '2026-08-17T18:06:12.341Z',
+    })
+  })
+
+  it('ignores failures that are not a lock conflict', () => {
+    expect(hostSupervisor.parseRunningServerConflict(
+      'listen EADDRINUSE: address already in use 127.0.0.1:24827',
+    )).toBeUndefined()
+    expect(hostSupervisor.parseRunningServerConflict('server already running')).toBeUndefined()
+  })
 })
 
 describe('desktop Host supervisor', () => {

apps/pythinker-code/src/cli/sub/server/run.ts

@@ -138,7 +138,10 @@ export function buildRunCommand(cmd: Command, options: { defaultOpen: boolean })
             `${error instanceof Error ? error.message : String(error)}\n`,
           );
         } finally {
-          process.exit(1);
+          // Errors that declare an exit code mean it: ServerLockedError uses 2 so
+          // callers can tell a single-instance conflict from a generic failure.
+          const declared = (error as { readonly exitCode?: unknown }).exitCode;
+          process.exit(typeof declared === 'number' ? declared : 1);
         }
       }
     });