repoburg 1.3.199 → 1.3.202

package/agent-pane/backend/src/repoburg/backend-resolver.test.ts

@@ -0,0 +1,356 @@
+import { describe, it, expect, vi, beforeEach, afterEach, type Mock } from 'vitest';
+import path from 'node:path';
+import {
+  resolveBackendUrl,
+  daemonBaseUrl,
+  clearResolverCache,
+  invalidateBackend,
+  type DaemonService,
+} from './backend-resolver.ts';
+
+/** Build a daemon service row. */
+function service(partial: Partial<DaemonService> & { port: number }): DaemonService {
+  return {
+    name: partial.name ?? `svc-${partial.port}`,
+    path: partial.path ?? '/tmp/does-not-match',
+    port: partial.port,
+    status: partial.status ?? 'running',
+    pid: partial.pid ?? null,
+  };
+}
+
+/** JSON Response helper. */
+const jsonResponse = (body: unknown, status = 200): Response =>
+  new Response(JSON.stringify(body), { status, headers: { 'Content-Type': 'application/json' } });
+
+/** Route table for the daemon + backend endpoints. */
+function mockFetchRoutes(routes: Array<{ match: (url: string, method: string) => boolean; respond: () => Response | Promise<Response> }>): Mock {
+  const mock = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = String(input);
+    const method = init?.method ?? 'GET';
+    for (const route of routes) {
+      if (route.match(url, method)) return route.respond();
+    }
+    return jsonResponse({ error: 'not found' }, 404);
+  });
+  vi.stubGlobal('fetch', mock);
+  return mock;
+}
+
+describe('backend-resolver', () => {
+  const DAEMON = 'http://localhost:9998';
+
+  beforeEach(() => {
+    delete process.env.REPOBURG_BACKEND_URL;
+    delete process.env.REPOBURG_DAEMON_URL;
+    clearResolverCache();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+  });
+
+  it('daemonBaseUrl defaults to 9998 and honors REPOBURG_DAEMON_URL', () => {
+    expect(daemonBaseUrl()).toBe('http://localhost:9998');
+    process.env.REPOBURG_DAEMON_URL = 'http://localhost:9999/';
+    expect(daemonBaseUrl()).toBe('http://localhost:9999');
+    delete process.env.REPOBURG_DAEMON_URL;
+  });
+
+  it('REPOBURG_BACKEND_URL bypasses the daemon entirely', async () => {
+    process.env.REPOBURG_BACKEND_URL = 'http://localhost:1234/';
+    const fetchMock = mockFetchRoutes([]);
+    const resolved = await resolveBackendUrl('/tmp/proj');
+    expect(resolved?.baseUrl).toBe('http://localhost:1234');
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it('throws a clear error when the daemon is unreachable', async () => {
+    const fetchMock = vi.fn().mockRejectedValue(new Error('fetch failed'));
+    vi.stubGlobal('fetch', fetchMock);
+    await expect(resolveBackendUrl('/tmp/proj')).rejects.toThrow(
+      /daemon not reachable at http:\/\/localhost:9998/,
+    );
+  });
+
+  it('returns a healthy running service matching the project path', async () => {
+    const abs = path.resolve('/tmp/proj');
+    const fetchMock = mockFetchRoutes([
+      { match: (u) => u === `${DAEMON}/health`, respond: () => jsonResponse({ status: 'ok' }) },
+      {
+        match: (u) => u === `${DAEMON}/services`,
+        respond: () => jsonResponse([service({ path: abs, port: 3402, name: 'proj' })]),
+      },
+      { match: (u) => u === 'http://localhost:3402/health', respond: () => jsonResponse({ status: 'ok' }) },
+    ]);
+
+    const resolved = await resolveBackendUrl('/tmp/proj');
+    expect(resolved).toEqual({ baseUrl: 'http://localhost:3402', port: 3402, name: 'proj' });
+    expect(fetchMock).toHaveBeenCalledTimes(3); // daemon health + list + backend health
+  });
+
+  it('reuses the cached resolution without re-listing daemon services', async () => {
+    const abs = path.resolve('/tmp/proj');
+    const fetchMock = mockFetchRoutes([
+      { match: (u) => u === `${DAEMON}/health`, respond: () => jsonResponse({ status: 'ok' }) },
+      {
+        match: (u) => u === `${DAEMON}/services`,
+        respond: () => jsonResponse([service({ path: abs, port: 3402, name: 'proj' })]),
+      },
+      { match: (u) => u === 'http://localhost:3402/health', respond: () => jsonResponse({ status: 'ok' }) },
+    ]);
+
+    await resolveBackendUrl('/tmp/proj');
+    await resolveBackendUrl('/tmp/proj');
+    // Second call: only the cached backend health probe — no daemon calls.
+    expect(fetchMock).toHaveBeenCalledTimes(4);
+    expect(fetchMock.mock.calls.every(([u]) => !String(u).includes('/services'))).toBe(false);
+  });
+
+  it('restarts a running service whose backend died, then returns it', async () => {
+    const abs = path.resolve('/tmp/proj');
+    let backendDead = true;
+    const restartMock = vi.fn();
+    mockFetchRoutes([
+      { match: (u) => u === `${DAEMON}/health`, respond: () => jsonResponse({ status: 'ok' }) },
+      {
+        match: (u) => u === `${DAEMON}/services`,
+        respond: () => jsonResponse([service({ path: abs, port: 3402, name: 'proj' })]),
+      },
+      {
+        match: (u) => u === 'http://localhost:3402/health',
+        respond: () => {
+          if (backendDead) return jsonResponse({ error: 'dead' }, 500);
+          return jsonResponse({ status: 'ok' });
+        },
+      },
+      {
+        match: (u, m) => u === `${DAEMON}/services/proj/restart` && m === 'POST',
+        respond: () => {
+          restartMock();
+          backendDead = false;
+          return jsonResponse(service({ path: abs, port: 3402, name: 'proj' }));
+        },
+      },
+    ]);
+
+    const resolved = await resolveBackendUrl('/tmp/proj');
+    expect(restartMock).toHaveBeenCalledTimes(1);
+    expect(resolved?.baseUrl).toBe('http://localhost:3402');
+  });
+
+  it('restarts a stopped service for the path', async () => {
+    const abs = path.resolve('/tmp/proj');
+    const fetchMock = mockFetchRoutes([
+      { match: (u) => u === `${DAEMON}/health`, respond: () => jsonResponse({ status: 'ok' }) },
+      {
+        match: (u) => u === `${DAEMON}/services`,
+        respond: () => jsonResponse([service({ path: abs, port: 3402, name: 'proj', status: 'stopped' })]),
+      },
+      {
+        match: (u, m) => u === `${DAEMON}/services/proj/restart` && m === 'POST',
+        respond: () => jsonResponse(service({ path: abs, port: 3402, name: 'proj' })),
+      },
+      { match: (u) => u === 'http://localhost:3402/health', respond: () => jsonResponse({ status: 'ok' }) },
+    ]);
+
+    const resolved = await resolveBackendUrl('/tmp/proj');
+    expect(resolved?.baseUrl).toBe('http://localhost:3402');
+    expect(fetchMock.mock.calls.some(([u, i]) => String(u).endsWith('/services/proj/restart') && (i as RequestInit)?.method === 'POST')).toBe(true);
+  });
+
+  it('starts a new backend via the daemon when no service matches', async () => {
+    const abs = path.resolve('/tmp/proj');
+    const fetchMock = mockFetchRoutes([
+      { match: (u) => u === `${DAEMON}/health`, respond: () => jsonResponse({ status: 'ok' }) },
+      { match: (u) => u === `${DAEMON}/services`, respond: () => jsonResponse([]) },
+      {
+        match: (u, m) => u === `${DAEMON}/services/start` && m === 'POST',
+        respond: () => jsonResponse(service({ path: abs, port: 3410, name: 'proj' }), 201),
+      },
+      { match: (u) => u === 'http://localhost:3410/health', respond: () => jsonResponse({ status: 'ok' }) },
+    ]);
+
+    const resolved = await resolveBackendUrl('/tmp/proj');
+    expect(resolved).toEqual({ baseUrl: 'http://localhost:3410', port: 3410, name: 'proj' });
+
+    const startCall = fetchMock.mock.calls.find(([u]) => String(u).endsWith('/services/start'));
+    expect(JSON.parse((startCall![1] as RequestInit).body as string)).toEqual({ path: abs });
+  });
+
+  it('surfaces the daemon message when start fails (e.g. 401 unauthorized)', async () => {
+    mockFetchRoutes([
+      { match: (u) => u === `${DAEMON}/health`, respond: () => jsonResponse({ status: 'ok' }) },
+      { match: (u) => u === `${DAEMON}/services`, respond: () => jsonResponse([]) },
+      {
+        match: (u) => u === `${DAEMON}/services/start`,
+        respond: () => jsonResponse({ error: 'Unauthorized', message: 'Please run repoburg login' }, 401),
+      },
+    ]);
+
+    await expect(resolveBackendUrl('/tmp/proj')).rejects.toThrow(/Please run repoburg login/);
+  });
+
+  it('autoStart=false returns null for stopped or missing services, resolves running ones', async () => {
+    const abs = path.resolve('/tmp/proj');
+    mockFetchRoutes([
+      { match: (u) => u === `${DAEMON}/health`, respond: () => jsonResponse({ status: 'ok' }) },
+      {
+        match: (u) => u === `${DAEMON}/services`,
+        respond: () => jsonResponse([service({ path: abs, port: 3402, name: 'proj', status: 'stopped' })]),
+      },
+    ]);
+    expect(await resolveBackendUrl('/tmp/proj', { autoStart: false })).toBeNull();
+    expect(await resolveBackendUrl('/tmp/other', { autoStart: false })).toBeNull();
+
+    clearResolverCache();
+    mockFetchRoutes([
+      { match: (u) => u === `${DAEMON}/health`, respond: () => jsonResponse({ status: 'ok' }) },
+      {
+        match: (u) => u === `${DAEMON}/services`,
+        respond: () => jsonResponse([service({ path: abs, port: 3402, name: 'proj' })]),
+      },
+      { match: (u) => u === 'http://localhost:3402/health', respond: () => jsonResponse({ status: 'ok' }) },
+    ]);
+    const resolved = await resolveBackendUrl('/tmp/proj', { autoStart: false });
+    expect(resolved?.baseUrl).toBe('http://localhost:3402');
+  });
+
+  it('autoStart=false returns null when the running backend is unhealthy (no restart)', async () => {
+    const abs = path.resolve('/tmp/proj');
+    const fetchMock = mockFetchRoutes([
+      { match: (u) => u === `${DAEMON}/health`, respond: () => jsonResponse({ status: 'ok' }) },
+      {
+        match: (u) => u === `${DAEMON}/services`,
+        respond: () => jsonResponse([service({ path: abs, port: 3402, name: 'proj' })]),
+      },
+      { match: (u) => u === 'http://localhost:3402/health', respond: () => jsonResponse({ error: 'dead' }, 500) },
+    ]);
+
+    expect(await resolveBackendUrl('/tmp/proj', { autoStart: false })).toBeNull();
+    expect(fetchMock.mock.calls.some(([u]) => String(u).includes('restart'))).toBe(false);
+  });
+
+  it('invalidateBackend drops the cache entry so the daemon is re-consulted', async () => {
+    const abs = path.resolve('/tmp/proj');
+    const fetchMock = mockFetchRoutes([
+      { match: (u) => u === `${DAEMON}/health`, respond: () => jsonResponse({ status: 'ok' }) },
+      {
+        match: (u) => u === `${DAEMON}/services`,
+        respond: () => jsonResponse([service({ path: abs, port: 3402, name: 'proj' })]),
+      },
+      { match: (u) => u === 'http://localhost:3402/health', respond: () => jsonResponse({ status: 'ok' }) },
+    ]);
+
+    const first = await resolveBackendUrl('/tmp/proj');
+    invalidateBackend(first!.baseUrl);
+    await resolveBackendUrl('/tmp/proj');
+    // Re-consulted the daemon after invalidation: 3 (first flow) + 3 (second flow).
+    expect(fetchMock).toHaveBeenCalledTimes(6);
+  });
+
+  it('throws when a freshly started backend never becomes healthy', async () => {
+    vi.useFakeTimers();
+    const abs = path.resolve('/tmp/proj');
+    mockFetchRoutes([
+      { match: (u) => u === `${DAEMON}/health`, respond: () => jsonResponse({ status: 'ok' }) },
+      { match: (u) => u === `${DAEMON}/services`, respond: () => jsonResponse([]) },
+      {
+        match: (u) => u === `${DAEMON}/services/start`,
+        respond: () => jsonResponse(service({ path: abs, port: 3410, name: 'proj' }), 201),
+      },
+      { match: (u) => u === 'http://localhost:3410/health', respond: () => jsonResponse({ error: 'dead' }, 500) },
+    ]);
+
+    const promise = resolveBackendUrl('/tmp/proj');
+    const assertion = expect(promise).rejects.toThrow(/did not become healthy within 30s/);
+    await vi.advanceTimersByTimeAsync(31_000);
+    await assertion;
+  });
+it('accepts a healthy running backend whose health projectPath matches the workspace', async () => {
+    const abs = path.resolve('/tmp/proj');
+    mockFetchRoutes([
+      { match: (u) => u === `${DAEMON}/health`, respond: () => jsonResponse({ status: 'ok' }) },
+      {
+        match: (u) => u === `${DAEMON}/services`,
+        respond: () => jsonResponse([service({ path: abs, port: 3402, name: 'proj' })]),
+      },
+      { match: (u) => u === 'http://localhost:3402/health', respond: () => jsonResponse({ status: 'ok', projectPath: abs }) },
+    ]);
+
+    const resolved = await resolveBackendUrl('/tmp/proj');
+    expect(resolved?.baseUrl).toBe('http://localhost:3402');
+  });
+
+  it('treats a projectPath mismatch as unhealthy (autoStart=false → null, no restart)', async () => {
+    const abs = path.resolve('/tmp/proj');
+    const fetchMock = mockFetchRoutes([
+      { match: (u) => u === `${DAEMON}/health`, respond: () => jsonResponse({ status: 'ok' }) },
+      {
+        match: (u) => u === `${DAEMON}/services`,
+        respond: () => jsonResponse([service({ path: abs, port: 3402, name: 'proj' })]),
+      },
+      { match: (u) => u === 'http://localhost:3402/health', respond: () => jsonResponse({ status: 'ok', projectPath: '/tmp/other-workspace' }) },
+    ]);
+
+    expect(await resolveBackendUrl('/tmp/proj', { autoStart: false })).toBeNull();
+    expect(fetchMock.mock.calls.some(([u]) => String(u).includes('restart'))).toBe(false);
+  });
+
+  it('restarts a running backend that serves a different workspace, then resolves it', async () => {
+    const abs = path.resolve('/tmp/proj');
+    let servingWrongWorkspace = true;
+    const restartMock = vi.fn();
+    mockFetchRoutes([
+      { match: (u) => u === `${DAEMON}/health`, respond: () => jsonResponse({ status: 'ok' }) },
+      {
+        match: (u) => u === `${DAEMON}/services`,
+        respond: () => jsonResponse([service({ path: abs, port: 3402, name: 'proj' })]),
+      },
+      {
+        match: (u) => u === 'http://localhost:3402/health',
+        respond: () =>
+          servingWrongWorkspace
+            ? jsonResponse({ status: 'ok', projectPath: '/tmp/other-workspace' })
+            : jsonResponse({ status: 'ok', projectPath: abs }),
+      },
+      {
+        match: (u, m) => u === `${DAEMON}/services/proj/restart` && m === 'POST',
+        respond: () => {
+          restartMock();
+          servingWrongWorkspace = false;
+          return jsonResponse(service({ path: abs, port: 3402, name: 'proj' }));
+        },
+      },
+    ]);
+
+    const resolved = await resolveBackendUrl('/tmp/proj');
+    expect(restartMock).toHaveBeenCalledTimes(1);
+    expect(resolved?.baseUrl).toBe('http://localhost:3402');
+  });
+
+  it('re-consults the daemon when the cached backend starts serving a different workspace', async () => {
+    const abs = path.resolve('/tmp/proj');
+    let projectPath = abs;
+    const fetchMock = mockFetchRoutes([
+      { match: (u) => u === `${DAEMON}/health`, respond: () => jsonResponse({ status: 'ok' }) },
+      {
+        match: (u) => u === `${DAEMON}/services`,
+        respond: () => jsonResponse([service({ path: abs, port: 3402, name: 'proj' })]),
+      },
+      { match: (u) => u === 'http://localhost:3402/health', respond: () => jsonResponse({ status: 'ok', projectPath }) },
+    ]);
+
+    // First resolve caches the backend (projectPath matches).
+    await resolveBackendUrl('/tmp/proj');
+
+    // The row got mis-mapped — the backend now serves another workspace.
+    projectPath = '/tmp/other-workspace';
+    fetchMock.mockClear();
+    await resolveBackendUrl('/tmp/proj', { autoStart: false });
+    // The cache was rejected and the daemon re-consulted (health probe rejected).
+    expect(fetchMock.mock.calls.some(([u]) => String(u) === 'http://localhost:3402/health')).toBe(true);
+    expect(fetchMock.mock.calls.some(([u]) => String(u) === `${DAEMON}/services`)).toBe(true);
+  });
+});

package/agent-pane/backend/src/repoburg/backend-resolver.ts

@@ -0,0 +1,261 @@
+/**
+ * Resolves the repoburg backend instance for a project path via the
+ * platform daemon (default http://localhost:9998).
+ *
+ * The daemon is the platform's process manager (PM2): it spawns one
+ * repoburg-backend per workspace with PORT (3400-3999) and
+ * REPOBURG_PROJECT_PATH. AgentPane never spawns backends itself.
+ *
+ * Resolution order:
+ *  1. REPOBURG_BACKEND_URL env → direct URL (dev override, daemon skipped)
+ *  2. cached resolution re-verified healthy
+ *  3. daemon GET /services → healthy running service for the path
+ *  4. daemon restart → stopped/dead service for the path
+ *  5. daemon POST /services/start → no service yet
+ *
+ * License auth: the daemon's file-based fallback (~/.repoburg/token.jwt)
+ * authorizes same-machine callers without a token.
+ */
+
+import path from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Daemon service row (GET /services). */
+export interface DaemonService {
+  name: string;
+  path: string;
+  port: number;
+  status: 'running' | 'stopped' | 'errored';
+  pid: number | null;
+}
+
+/** Root backend /health payload (projectPath is additive — absent on pre-v2 builds). */
+interface HealthPayload {
+  status: string;
+  projectPath?: string;
+}
+
+/** A resolved backend instance to connect to. */
+export interface ResolvedBackend {
+  baseUrl: string;
+  port: number;
+  name: string;
+}
+
+export interface ResolveOptions {
+  /** false = never start/restart; return null when no healthy instance runs. */
+  autoStart?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+/** Health probe interval/timeout for freshly started backends (ms). */
+const HEALTH_POLL_INTERVAL_MS = 1000;
+const HEALTH_TIMEOUT_MS = 30_000;
+
+/** Daemon base URL. */
+export function daemonBaseUrl(): string {
+  return (process.env.REPOBURG_DAEMON_URL || 'http://localhost:9998').replace(/\/+$/, '');
+}
+
+// ---------------------------------------------------------------------------
+// HTTP helpers
+// ---------------------------------------------------------------------------
+
+class HttpError extends Error {
+  constructor(
+    readonly status: number,
+    readonly body: string,
+    readonly url: string,
+  ) {
+    super(`${url} failed: ${status} ${body}`);
+  }
+}
+
+/** JSON GET/POST with a timeout. Throws HttpError on non-OK responses. */
+async function fetchJson<T>(url: string, init?: RequestInit, timeoutMs = 5000): Promise<T> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let response: Response;
+  try {
+    response = await fetch(url, { ...init, signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+  const text = await response.text();
+  if (!response.ok) {
+    throw new HttpError(response.status, text, url);
+  }
+  try {
+    return JSON.parse(text) as T;
+  } catch {
+    throw new Error(`Unexpected non-JSON response from ${url}`);
+  }
+}
+
+/** Extract a human message from a daemon HttpError body. */
+function daemonErrorMessage(err: unknown): string {
+  if (err instanceof HttpError) {
+    try {
+      const parsed = JSON.parse(err.body) as { message?: string; error?: string };
+      return parsed.message || parsed.error || err.body;
+    } catch {
+      return err.body;
+    }
+  }
+  return (err as Error).message;
+}
+
+// ---------------------------------------------------------------------------
+// Resolution
+// ---------------------------------------------------------------------------
+
+/** Cached resolutions per resolved project path. */
+const resolvedCache = new Map<string, ResolvedBackend>();
+
+/** Test hook — clear the resolution cache. */
+export function clearResolverCache(): void {
+  resolvedCache.clear();
+}
+
+/** Drop cached resolutions pointing at the given base URL (dead backend). */
+export function invalidateBackend(baseUrl: string): void {
+  for (const [key, value] of resolvedCache) {
+    if (value.baseUrl === baseUrl) resolvedCache.delete(key);
+  }
+}
+
+/**
+ * Probe a backend's /health endpoint (short timeout). With expectedPath, a
+ * projectPath mismatch means unhealthy: the backend serves a different
+ * workspace than the daemon row claims (mis-mapped service).
+ */
+async function backendHealthy(baseUrl: string, expectedPath?: string): Promise<boolean> {
+  try {
+    const health = await fetchJson<HealthPayload>(`${baseUrl}/health`, undefined, 2000);
+    if (health.status !== 'ok') return false;
+    if (expectedPath && health.projectPath) {
+      return path.resolve(health.projectPath) === path.resolve(expectedPath);
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Wait until the backend on baseUrl reports healthy (for expectedPath). */
+async function waitForHealthy(baseUrl: string, name: string, expectedPath?: string): Promise<void> {
+  const deadline = Date.now() + HEALTH_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    if (await backendHealthy(baseUrl, expectedPath)) return;
+    await new Promise((resolve) => setTimeout(resolve, HEALTH_POLL_INTERVAL_MS));
+  }
+  throw new Error(
+    `Backend '${name}' on ${baseUrl} did not become healthy within ${HEALTH_TIMEOUT_MS / 1000}s. Check daemon logs: repoburg logs ${name}`,
+  );
+}
+
+function serviceBaseUrl(service: DaemonService): string {
+  return `http://localhost:${service.port}`;
+}
+
+/** Ask the daemon to (re)start the named service. */
+async function restartService(daemon: string, name: string): Promise<void> {
+  try {
+    await fetchJson<DaemonService>(`${daemon}/services/${name}/restart`, { method: 'POST' });
+  } catch (err) {
+    throw new Error(`Daemon failed to restart backend '${name}': ${daemonErrorMessage(err)}`);
+  }
+}
+
+/** Ask the daemon to start a backend for the project path. */
+async function startService(daemon: string, projectPath: string): Promise<DaemonService> {
+  try {
+    return await fetchJson<DaemonService>(`${daemon}/services/start`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ path: projectPath }),
+    });
+  } catch (err) {
+    throw new Error(`Daemon failed to start backend for ${projectPath}: ${daemonErrorMessage(err)}`);
+  }
+}
+
+function cache(absPath: string, service: DaemonService): ResolvedBackend {
+  const resolved: ResolvedBackend = {
+    baseUrl: serviceBaseUrl(service),
+    port: service.port,
+    name: service.name,
+  };
+  resolvedCache.set(absPath, resolved);
+  return resolved;
+}
+
+/**
+ * Resolve the backend instance for a project path.
+ * Throws on unreachable daemon / start failure; returns null only when
+ * autoStart=false and no healthy instance is running.
+ */
+export async function resolveBackendUrl(
+  projectPath: string,
+  opts: ResolveOptions = {},
+): Promise<ResolvedBackend | null> {
+  const autoStart = opts.autoStart !== false;
+
+  // 1. Explicit env override — direct connection, daemon skipped.
+  const envUrl = process.env.REPOBURG_BACKEND_URL;
+  if (envUrl) {
+    return { baseUrl: envUrl.replace(/\/+$/, ''), port: 0, name: 'REPOBURG_BACKEND_URL' };
+  }
+
+  const absPath = path.resolve(projectPath);
+  const daemon = daemonBaseUrl();
+
+  // 2. Cached resolution, re-verified healthy (and serving this workspace).
+  const cached = resolvedCache.get(absPath);
+  if (cached && (await backendHealthy(cached.baseUrl, absPath))) {
+    return cached;
+  }
+
+  // 3. Daemon must be reachable.
+  try {
+    await fetchJson(`${daemon}/health`, undefined, 3000);
+  } catch {
+    throw new Error(
+      `Repoburg daemon not reachable at ${daemon}. Start it with 'repoburg-daemon', or set REPOBURG_BACKEND_URL to a running backend.`,
+    );
+  }
+
+  const services = await fetchJson<DaemonService[]>(`${daemon}/services`);
+  const match = services.find((s) => s.path === absPath);
+
+  if (match && match.status === 'running') {
+    if (await backendHealthy(serviceBaseUrl(match), absPath)) {
+      return cache(absPath, match);
+    }
+    if (!autoStart) return null;
+    // Unhealthy or serving a different workspace — the process is wrong
+    // for this path. Restart via the daemon.
+    await restartService(daemon, match.name);
+    await waitForHealthy(serviceBaseUrl(match), match.name, absPath);
+    return cache(absPath, match);
+  }
+
+  if (!autoStart) return null; // stopped/errored/missing — left to the first turn.
+
+  if (match) {
+    await restartService(daemon, match.name);
+    await waitForHealthy(serviceBaseUrl(match), match.name, absPath);
+    return cache(absPath, match);
+  }
+
+  // No service for this path yet — start one.
+  const service = await startService(daemon, absPath);
+  await waitForHealthy(serviceBaseUrl(service), service.name, absPath);
+  return cache(absPath, service);
+}