@venturewild/workspace 0.1.0 → 0.1.2

package/server/src/supervisor.mjs

@@ -0,0 +1,217 @@
+// WorkspaceSupervisor — keeps the wild-workspace server alive in the background.
+//
+// The server itself auto-starts the bmo-sync daemon on boot (DaemonSupervisor),
+// so keeping the server up brings the whole local stack — public URL included —
+// back to life. This is the watchdog half of the always-on feature
+// (docs/always-on-design.md); `service.mjs` is the per-OS autostart half that
+// launches this hidden at login via `wild-workspace service run`.
+//
+// Design (all proven on Windows incl. a real reboot, 2026-05-30):
+//  - Health-driven: polls GET /api/health and (re)spawns the server only when
+//    it is down — so it never fights a server someone else started and handles
+//    crash recovery naturally.
+//  - Singleton: an exclusive lockfile in the machine-global dir
+//    (~/.wild-workspace, NEVER the synced workspace — locked principle #1).
+//    A stale lock whose pid is dead is taken over.
+//  - Exponential backoff (capped) so a crash-looping server can't spin the CPU.
+//  - Everything is logged — silent death is the #1 un-debuggable failure mode.
+//
+// Every external touch-point (spawn, health probe, clock) is an injected seam
+// so the suite never spawns a real process.
+
+import { spawn } from 'node:child_process';
+import http from 'node:http';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_SERVER_ENTRY = path.join(__dirname, 'index.mjs');
+
+/** Resolve true iff the local server answers /api/health. Never throws. */
+export function probeHealth(port, timeoutMs = 2500) {
+  return new Promise((resolve) => {
+    const req = http.get(
+      { host: '127.0.0.1', port, path: '/api/health', timeout: timeoutMs },
+      (res) => { res.resume(); resolve(res.statusCode > 0); },
+    );
+    req.on('error', () => resolve(false));
+    req.on('timeout', () => { req.destroy(); resolve(false); });
+  });
+}
+
+export class WorkspaceSupervisor {
+  constructor({
+    serverEntry = DEFAULT_SERVER_ENTRY,
+    workspaceDir = process.cwd(),
+    port = Number(process.env.WILD_WORKSPACE_PORT || 5173),
+    globalDir = path.join(os.homedir(), '.wild-workspace'),
+    node = process.execPath,
+    pollMs = 3000,
+    backoffStartMs = 1000,
+    backoffMaxMs = 30000,
+    probeTimeoutMs = 2500,
+    spawnImpl = spawn,
+    probeImpl = probeHealth,
+    nowImpl = () => Date.now(),
+    env = process.env,
+    crashLoopThreshold = 3,
+    diagnosticsImpl = null,
+  } = {}) {
+    Object.assign(this, {
+      serverEntry, workspaceDir, port, globalDir, node, pollMs,
+      backoffStartMs, backoffMaxMs, probeTimeoutMs, spawnImpl, probeImpl, nowImpl, env,
+      crashLoopThreshold, diagnosticsImpl,
+    });
+    this.logFile = path.join(globalDir, 'supervisor.log');
+    this.serverLogFile = path.join(globalDir, 'server.out.log');
+    this.lockFile = path.join(globalDir, 'supervisor.lock');
+    this.child = null;
+    this.backoff = backoffStartMs;
+    this.lastSpawn = 0;
+    this.timer = null;
+    this.spawnCount = 0; //        consecutive spawns without becoming healthy
+    this.pushedThisEpisode = false; // crash-loop diagnostics pushed once per episode
+  }
+
+  log(msg) {
+    try { fs.appendFileSync(this.logFile, `[${new Date().toISOString()}] ${msg}\n`); } catch { /* best-effort */ }
+  }
+
+  /** Is a pid alive? EPERM means "exists, not ours" → still alive. */
+  pidAlive(pid) {
+    try { process.kill(pid, 0); return true; } catch (e) { return !!(e && e.code === 'EPERM'); }
+  }
+
+  /** Exclusive lock; take over ONLY a stale lock (recorded pid no longer alive). */
+  acquireLock() {
+    try { fs.mkdirSync(this.globalDir, { recursive: true }); } catch { /* surfaced below */ }
+    try {
+      const fd = fs.openSync(this.lockFile, 'wx');
+      fs.writeSync(fd, String(process.pid));
+      fs.closeSync(fd);
+      return true;
+    } catch {
+      let old = null;
+      try { old = Number(fs.readFileSync(this.lockFile, 'utf8').trim()); } catch { /* unreadable */ }
+      if (old && this.pidAlive(old)) {
+        this.log(`live supervisor pid=${old} already running; exiting`);
+        return false;
+      }
+      try { fs.writeFileSync(this.lockFile, String(process.pid)); this.log('took over stale lock'); return true; }
+      catch { return false; }
+    }
+  }
+
+  releaseLock() {
+    try {
+      if (Number(fs.readFileSync(this.lockFile, 'utf8').trim()) === process.pid) fs.unlinkSync(this.lockFile);
+    } catch { /* already gone */ }
+  }
+
+  spawnServer() {
+    let out = 'ignore';
+    try { out = fs.openSync(this.serverLogFile, 'a'); } catch { /* output discarded */ }
+    this.child = this.spawnImpl(this.node, [this.serverEntry], {
+      cwd: this.workspaceDir,
+      windowsHide: true,
+      stdio: ['ignore', out, out],
+      env: { ...this.env, WILD_WORKSPACE_NO_OPEN: '1', WILD_WORKSPACE_DIR: this.workspaceDir },
+    });
+    if (typeof out === 'number') { try { fs.closeSync(out); } catch { /* parent fd */ } }
+    this.lastSpawn = this.nowImpl();
+    const pid = this.child && this.child.pid;
+    this.log(`spawned server pid=${pid} (backoff=${this.backoff}ms)`);
+    if (this.child && this.child.on) {
+      this.child.on('exit', (code, sig) => { this.log(`server pid=${pid} exited code=${code} sig=${sig}`); this.child = null; });
+    }
+    return this.child;
+  }
+
+  /** One supervision step. Returns its decision (exposed for tests). */
+  async tick() {
+    if (await this.probeImpl(this.port, this.probeTimeoutMs)) {
+      this.backoff = this.backoffStartMs; // healthy → reset backoff
+      this.spawnCount = 0; //              healthy → not a crash loop
+      this.pushedThisEpisode = false;
+      return 'healthy';
+    }
+    if (this.child) return 'booting';                                  // spawned, still coming up
+    if (this.nowImpl() - this.lastSpawn < this.backoff) return 'backoff';
+    this.spawnServer();
+    this.backoff = Math.min(this.backoff * 2, this.backoffMaxMs);
+    this.spawnCount += 1;
+    // Crash loop: the server won't stay up, so the operator channel (which rides
+    // the :5173 server) can't reach this machine at all. Push an install-down
+    // `doctor` bundle to bmo-sync ONCE per episode so support sees it anyway —
+    // the install-failed-before-server-up case (docs/user-experience.md §5).
+    if (this.spawnCount >= this.crashLoopThreshold && !this.pushedThisEpisode) {
+      this.pushedThisEpisode = true;
+      Promise.resolve(this.pushDiagnostics()).catch((e) => this.log(`diag push error: ${e?.message || e}`));
+    }
+    return 'spawned';
+  }
+
+  /**
+   * Push an install-down diagnostic bundle to bmo-sync. Injected (`diagnosticsImpl`)
+   * in tests; the real path is consent- + token-gated and never runs under the
+   * test runner. Best-effort, never throws into the supervision loop.
+   */
+  async pushDiagnostics() {
+    if (this.diagnosticsImpl) return this.diagnosticsImpl(this);
+    if (process.env.VITEST || process.env.NODE_ENV === 'test') return;
+    try {
+      const [{ buildConfig }, { runDoctor }, { loadObservabilityConsent }] = await Promise.all([
+        import('./config.mjs'),
+        import('./doctor.mjs'),
+        import('./observability.mjs'),
+      ]);
+      const config = buildConfig({ workspaceDir: this.workspaceDir, port: this.port });
+      if (!config.accountToken) return; //                        can't key it to a user
+      if (process.env.WILD_WORKSPACE_NO_TELEMETRY === '1') return; // kill switch
+      if (!loadObservabilityConsent(config.dataDir).enabled) return; // consent
+      const report = await runDoctor({ config });
+      const url = `${config.bmoSyncServerUrl.replace(/\/$/, '')}/api/telemetry`;
+      const ctrl = new AbortController();
+      const t = setTimeout(() => ctrl.abort(), 5000);
+      try {
+        await fetch(url, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({
+            account_token: config.accountToken,
+            slug: config.account?.slug || null,
+            workspace_id: config.workspaceId,
+            kind: 'install-down',
+            doctor: report,
+            sent_at: Math.floor(Date.now() / 1000),
+          }),
+          signal: ctrl.signal,
+        });
+        this.log(`pushed install-down diagnostics (fail=${report.summary?.fail})`);
+      } finally {
+        clearTimeout(t);
+      }
+    } catch (e) {
+      this.log(`diagnostics push failed: ${e?.message || e}`);
+    }
+  }
+
+  /** Acquire the lock and start the supervision loop. Idempotent across processes. */
+  start() {
+    if (!this.acquireLock()) return { started: false, reason: 'already-running' };
+    process.on('exit', () => this.releaseLock());
+    process.on('SIGTERM', () => process.exit(0));
+    process.on('SIGINT', () => process.exit(0));
+    this.log(`supervisor start pid=${process.pid} watching http://127.0.0.1:${this.port}/api/health (workspace=${this.workspaceDir})`);
+    this.timer = setInterval(() => { this.tick().catch((e) => this.log(`tick error: ${e?.message || e}`)); }, this.pollMs);
+    this.tick().catch((e) => this.log(`tick error: ${e?.message || e}`));
+    return { started: true };
+  }
+
+  stop() {
+    if (this.timer) { clearInterval(this.timer); this.timer = null; }
+    this.releaseLock();
+  }
+}

package/server/src/sync.mjs

@@ -1,176 +1,248 @@
-// bmo-sync folder sharing — wild-workspace's control plane for the daemon.
-//
-// wild-workspace does not run the sync engine; the bmo-sync daemon does
-// (a separate local process — see bmo-sync/daemon/README.md). This module is
-// the thin HTTP client wild-workspace uses to drive it:
-//
-//   - pair / detach / list a workspace folder against the local daemon
-//     (http://127.0.0.1:8320);
-//   - mint an invite against the central server's admin API — but only when
-//     an admin key is configured. Most installs only ever *redeem* invites,
-//     and that path runs entirely through the daemon and needs no secret.
-//
-// The daemon may not be running. Read paths (health / listWorkspaces /
-// status) degrade to an "offline" result instead of throwing; explicit
-// actions (pair / detach / createInvite) throw a readable error for the UI.
-
-const DAEMON_TIMEOUT_MS = 4000;
-// Pairing and invite creation reach the central server on Fly.io, which can
-// cold-start (~1s+) when idle — give those calls a longer leash.
-const SERVER_TIMEOUT_MS = 12000;
-
-export class SyncControl {
-  /**
-   * @param {object}        opts
-   * @param {string}        opts.daemonHttpUrl     daemon HTTP origin, e.g. http://127.0.0.1:8320
-   * @param {string}        opts.bmoSyncServerUrl  central server, e.g. https://sync.venturewild.llc
-   * @param {string|null}  [opts.adminKey]         central-server X-Admin-Key; null = redeem-only
-   * @param {typeof fetch} [opts.fetchImpl]        injectable fetch (tests)
-   */
-  constructor({ daemonHttpUrl, bmoSyncServerUrl, adminKey = null, fetchImpl } = {}) {
-    this.daemonBase = trimSlash(daemonHttpUrl) || 'http://127.0.0.1:8320';
-    this.serverBase = trimSlash(bmoSyncServerUrl) || 'https://sync.venturewild.llc';
-    this.adminKey = adminKey || null;
-    this._fetch = fetchImpl || globalThis.fetch;
-  }
-
-  /** True when this install can mint invites (an admin key is configured). */
-  get canInvite() {
-    return Boolean(this.adminKey);
-  }
-
-  /** Liveness of the local daemon. Never throws. */
-  async health() {
-    try {
-      const res = await this._fetch(`${this.daemonBase}/health`, {
-        signal: AbortSignal.timeout(DAEMON_TIMEOUT_MS),
-      });
-      if (!res.ok) return { running: false };
-      const body = await res.json().catch(() => ({}));
-      return { running: body?.status === 'ok' };
-    } catch {
-      return { running: false };
-    }
-  }
-
-  /** Paired workspaces the daemon is syncing. [] when the daemon is down. */
-  async listWorkspaces() {
-    try {
-      const res = await this._fetch(`${this.daemonBase}/api/workspaces`, {
-        signal: AbortSignal.timeout(DAEMON_TIMEOUT_MS),
-      });
-      if (!res.ok) return [];
-      const body = await res.json().catch(() => ({}));
-      return Array.isArray(body?.workspaces) ? body.workspaces : [];
-    } catch {
-      return [];
-    }
-  }
-
-  /**
-   * Snapshot for the Sync panel: daemon liveness, paired workspaces, and
-   * whether this install can mint invites. Never throws — a missing daemon
-   * is a normal, displayable state.
-   */
-  async status() {
-    const [health, workspaces] = await Promise.all([
-      this.health(),
-      this.listWorkspaces(),
-    ]);
-    return {
-      daemon: health,
-      workspaces,
-      paired: workspaces.length > 0,
-      canInvite: this.canInvite,
-    };
-  }
-
-  /**
-   * Pair this workspace folder with a shared project by redeeming an invite.
-   * The daemon redeems against the central server, persists the pairing, and
-   * starts syncing `rootPath`. Throws a readable error on a bad invite or an
-   * unreachable daemon.
-   */
-  async pair(inviteCode, rootPath) {
-    const code = String(inviteCode || '').trim();
-    if (!code) throw new Error('An invite code is required.');
-    if (!rootPath) throw new Error('No workspace folder to pair.');
-    const res = await this._daemonFetch(`${this.daemonBase}/api/pair`, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ inviteCode: code, rootPath }),
-      // Pairing redeems against the central server — allow for a cold start.
-      signal: AbortSignal.timeout(SERVER_TIMEOUT_MS),
-    });
-    const body = await res.json().catch(() => ({}));
-    if (!res.ok) {
-      throw new Error(body?.error || `Pairing failed (HTTP ${res.status}).`);
-    }
-    return body.workspace || body;
-  }
-
-  /** Stop syncing a workspace and forget the pairing. */
-  async detach(workspaceId) {
-    const id = String(workspaceId || '').trim();
-    if (!id) throw new Error('A workspace id is required.');
-    const res = await this._daemonFetch(
-      `${this.daemonBase}/api/workspaces/${encodeURIComponent(id)}`,
-      { method: 'DELETE', signal: AbortSignal.timeout(DAEMON_TIMEOUT_MS) },
-    );
-    const body = await res.json().catch(() => ({}));
-    if (!res.ok) {
-      throw new Error(body?.error || `Disconnect failed (HTTP ${res.status}).`);
-    }
-    return { detached: Boolean(body.detached) };
-  }
-
-  /**
-   * Mint an invite code for a project on the central server. Requires an
-   * admin key; callers should check `canInvite` first and fall back to the
-   * paste-a-code flow when it is false.
-   */
-  async createInvite({ projectCode, displayName, expiresHours = 168 } = {}) {
-    if (!this.adminKey) {
-      throw new Error(
-        'Creating invites needs a bmo-sync admin key (set BMO_SYNC_ADMIN_KEY). ' +
-          'Without one, ask whoever owns the shared folder to send you a code.',
-      );
-    }
-    if (!projectCode) throw new Error('A paired project is required to invite into.');
-    let res;
-    try {
-      res = await this._fetch(`${this.serverBase}/api/admin/invites`, {
-        method: 'POST',
-        headers: { 'content-type': 'application/json', 'x-admin-key': this.adminKey },
-        body: JSON.stringify({
-          project_code: projectCode,
-          display_name: displayName || 'Collaborator',
-          expires_hours: Number(expiresHours) || 168,
-        }),
-        signal: AbortSignal.timeout(SERVER_TIMEOUT_MS),
-      });
-    } catch {
-      throw new Error('Could not reach the bmo-sync server. Check your connection.');
-    }
-    const body = await res.json().catch(() => ({}));
-    if (!res.ok) {
-      throw new Error(
-        body?.message || body?.error || `Invite creation failed (HTTP ${res.status}).`,
-      );
-    }
-    return { code: body.code, projectCode: body.project_code, expiresAt: body.expires_at };
-  }
-
-  /** A daemon fetch that turns a connection failure into a readable error. */
-  async _daemonFetch(url, init) {
-    try {
-      return await this._fetch(url, init);
-    } catch {
-      throw new Error("The bmo-sync daemon isn't running. Start it, then try again.");
-    }
-  }
-}
-
-function trimSlash(u) {
-  return typeof u === 'string' ? u.replace(/\/+$/, '') : '';
-}
+// bmo-sync folder sharing — wild-workspace's control plane for the daemon.
+//
+// wild-workspace does not run the sync engine; the bmo-sync daemon does
+// (a separate local process — see bmo-sync/daemon/README.md). This module is
+// the thin HTTP client wild-workspace uses to drive it:
+//
+//   - pair / detach / list a workspace folder against the local daemon
+//     (http://127.0.0.1:8320);
+//   - mint an invite against the central server's admin API — but only when
+//     an admin key is configured. Most installs only ever *redeem* invites,
+//     and that path runs entirely through the daemon and needs no secret.
+//
+// The daemon may not be running. Read paths (health / listWorkspaces /
+// status) degrade to an "offline" result instead of throwing; explicit
+// actions (pair / detach / createInvite) throw a readable error for the UI.
+
+const DAEMON_TIMEOUT_MS = 4000;
+// Pairing and invite creation reach the central server on Fly.io, which can
+// cold-start (~1s+) when idle — give those calls a longer leash.
+const SERVER_TIMEOUT_MS = 12000;
+
+export class SyncControl {
+  /**
+   * @param {object}        opts
+   * @param {string}        opts.daemonHttpUrl     daemon HTTP origin, e.g. http://127.0.0.1:8320
+   * @param {string}        opts.bmoSyncServerUrl  central server, e.g. https://sync.venturewild.llc
+   * @param {string|null}  [opts.adminKey]         central-server X-Admin-Key; null = redeem-only
+   * @param {typeof fetch} [opts.fetchImpl]        injectable fetch (tests)
+   */
+  constructor({ daemonHttpUrl, bmoSyncServerUrl, adminKey = null, fetchImpl } = {}) {
+    this.daemonBase = trimSlash(daemonHttpUrl) || 'http://127.0.0.1:8320';
+    this.serverBase = trimSlash(bmoSyncServerUrl) || 'https://sync.venturewild.llc';
+    this.adminKey = adminKey || null;
+    this._fetch = fetchImpl || globalThis.fetch;
+  }
+
+  /** True when this install can mint invites (an admin key is configured). */
+  get canInvite() {
+    return Boolean(this.adminKey);
+  }
+
+  /** Liveness of the local daemon. Never throws. */
+  async health() {
+    try {
+      const res = await this._fetch(`${this.daemonBase}/health`, {
+        signal: AbortSignal.timeout(DAEMON_TIMEOUT_MS),
+      });
+      if (!res.ok) return { running: false };
+      const body = await res.json().catch(() => ({}));
+      return { running: body?.status === 'ok' };
+    } catch {
+      return { running: false };
+    }
+  }
+
+  /** Paired workspaces the daemon is syncing. [] when the daemon is down. */
+  async listWorkspaces() {
+    try {
+      const res = await this._fetch(`${this.daemonBase}/api/workspaces`, {
+        signal: AbortSignal.timeout(DAEMON_TIMEOUT_MS),
+      });
+      if (!res.ok) return [];
+      const body = await res.json().catch(() => ({}));
+      return Array.isArray(body?.workspaces) ? body.workspaces : [];
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Snapshot for the Sync panel: daemon liveness, paired workspaces, and
+   * whether this install can mint invites. Never throws — a missing daemon
+   * is a normal, displayable state.
+   */
+  async status() {
+    const [health, workspaces] = await Promise.all([
+      this.health(),
+      this.listWorkspaces(),
+    ]);
+    return {
+      daemon: health,
+      workspaces,
+      paired: workspaces.length > 0,
+      canInvite: this.canInvite,
+    };
+  }
+
+  /**
+   * Pair this workspace folder with a shared project by redeeming an invite.
+   * The daemon redeems against the central server, persists the pairing, and
+   * starts syncing `rootPath`. Throws a readable error on a bad invite or an
+   * unreachable daemon.
+   */
+  async pair(inviteCode, rootPath) {
+    const code = String(inviteCode || '').trim();
+    if (!code) throw new Error('An invite code is required.');
+    if (!rootPath) throw new Error('No workspace folder to pair.');
+    const res = await this._daemonFetch(`${this.daemonBase}/api/pair`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ inviteCode: code, rootPath }),
+      // Pairing redeems against the central server — allow for a cold start.
+      signal: AbortSignal.timeout(SERVER_TIMEOUT_MS),
+    });
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      throw new Error(body?.error || `Pairing failed (HTTP ${res.status}).`);
+    }
+    return body.workspace || body;
+  }
+
+  /** Stop syncing a workspace and forget the pairing. */
+  async detach(workspaceId) {
+    const id = String(workspaceId || '').trim();
+    if (!id) throw new Error('A workspace id is required.');
+    const res = await this._daemonFetch(
+      `${this.daemonBase}/api/workspaces/${encodeURIComponent(id)}`,
+      { method: 'DELETE', signal: AbortSignal.timeout(DAEMON_TIMEOUT_MS) },
+    );
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      throw new Error(body?.error || `Disconnect failed (HTTP ${res.status}).`);
+    }
+    return { detached: Boolean(body.detached) };
+  }
+
+  /**
+   * Mint an invite code for a project on the central server. Requires an
+   * admin key; callers should check `canInvite` first and fall back to the
+   * paste-a-code flow when it is false.
+   */
+  async createInvite({ projectCode, displayName, expiresHours = 168 } = {}) {
+    if (!this.adminKey) {
+      throw new Error(
+        'Creating invites needs a bmo-sync admin key (set BMO_SYNC_ADMIN_KEY). ' +
+          'Without one, ask whoever owns the shared folder to send you a code.',
+      );
+    }
+    if (!projectCode) throw new Error('A paired project is required to invite into.');
+    let res;
+    try {
+      res = await this._fetch(`${this.serverBase}/api/admin/invites`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', 'x-admin-key': this.adminKey },
+        body: JSON.stringify({
+          project_code: projectCode,
+          display_name: displayName || 'Collaborator',
+          expires_hours: Number(expiresHours) || 168,
+        }),
+        signal: AbortSignal.timeout(SERVER_TIMEOUT_MS),
+      });
+    } catch {
+      throw new Error('Could not reach the bmo-sync server. Check your connection.');
+    }
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      throw new Error(
+        body?.message || body?.error || `Invite creation failed (HTTP ${res.status}).`,
+      );
+    }
+    return { code: body.code, projectCode: body.project_code, expiresAt: body.expires_at };
+  }
+
+  /** A daemon fetch that turns a connection failure into a readable error. */
+  async _daemonFetch(url, init) {
+    try {
+      return await this._fetch(url, init);
+    } catch {
+      throw new Error("The bmo-sync daemon isn't running. Start it, then try again.");
+    }
+  }
+
+  // ── C12-e: conflict surface ──────────────────────────────────────────
+  // The daemon emits SyncEvent::Conflict via /api/events (already piped
+  // into the wild-workspace ActivityBus by DaemonBridge); these methods
+  // are the explicit "give me / resolve" operations behind the badge
+  // and CLI.
+
+  /** All open conflicts across every paired workspace. [] when daemon down. */
+  async listConflicts() {
+    try {
+      const res = await this._fetch(`${this.daemonBase}/api/conflicts`, {
+        signal: AbortSignal.timeout(DAEMON_TIMEOUT_MS),
+      });
+      if (!res.ok) return [];
+      const body = await res.json().catch(() => ({}));
+      return Array.isArray(body?.conflicts) ? body.conflicts : [];
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Fetch one conflict's mine/theirs bytes (base64) plus the row. Used by
+   * the human-fallback diff panel + the `wild_conflicts_view` agent tool.
+   */
+  async viewConflict(workspaceId, path) {
+    if (!workspaceId) throw new Error('workspaceId is required');
+    if (!path) throw new Error('path is required');
+    const url =
+      `${this.daemonBase}/api/conflicts/` +
+      `${encodeURIComponent(workspaceId)}/` +
+      path.split('/').map(encodeURIComponent).join('/');
+    const res = await this._daemonFetch(url, {
+      signal: AbortSignal.timeout(DAEMON_TIMEOUT_MS),
+    });
+    const body = await res.json().catch(() => ({}));
+    if (res.status === 404) return null;
+    if (!res.ok) {
+      throw new Error(body?.error || `Conflict view failed (HTTP ${res.status}).`);
+    }
+    return body;
+  }
+
+  /**
+   * Resolve a conflict. `action` is `keep_mine` or `take_theirs`. The
+   * server-mediated multi-peer broadcast is a V1.1 follow-up; for V1
+   * this is local-only.
+   */
+  async resolveConflict(workspaceId, path, action) {
+    const verb = String(action || '').trim();
+    if (!['keep_mine', 'take_theirs'].includes(verb)) {
+      throw new Error('action must be "keep_mine" or "take_theirs".');
+    }
+    // GET = view, POST = resolve on the same URL — the daemon's route was
+    // collapsed because axum 0.8 disallows a literal segment after a
+    // `{*path}` catchall.
+    const url =
+      `${this.daemonBase}/api/conflicts/` +
+      `${encodeURIComponent(workspaceId)}/` +
+      path.split('/').map(encodeURIComponent).join('/');
+    const res = await this._daemonFetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ action: verb }),
+      signal: AbortSignal.timeout(DAEMON_TIMEOUT_MS),
+    });
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      throw new Error(body?.error || `Resolve failed (HTTP ${res.status}).`);
+    }
+    return { ok: true };
+  }
+}
+
+function trimSlash(u) {
+  return typeof u === 'string' ? u.replace(/\/+$/, '') : '';
+}