feat: serve from any dir + project-scope server-backed CLI commands

Two gaps surfaced while testing the multi-project flow:

- `webmux serve` no longer requires a `.webmux.yaml` in the cwd. It serves every
  known project (from ~/.webmux/projects.json) on one port and auto-adds the cwd
  repo when it is a webmux project; a fresh dir just shows the empty state.
- Server-backed CLI commands (`send`, `tab`, `linear`, `oneshot`) now resolve
  the cwd's project and target `/<prefix>/api/...` instead of the bare,
  now-nonexistent unprefixed routes. Added `resolveProjectRoot` /
  `resolveProjectBaseUrl` in shared.ts (matches the server's `projectRoot`,
  looks the project up via /api/projects). Falls back to the unscoped base when
  the root can't be determined; clear error when the repo isn't a served project.
  oneshot also prefixes its agents WebSocket URL.

Verified: `send` to a missing branch returns a clean "Worktree not found" (i.e.
it reached the prefixed endpoint); `webmux serve` from /tmp no longer errors on
a missing config. Suite green: backend 454, frontend 114, bin+contract 185.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: hugocasa

bin/src/linear-commands.ts

@@ -1,5 +1,5 @@
 import { createApi, parseLinearTarget, type PostWorktreeToLinearTarget } from "@webmux/api-contract";
-import { CommandUsageError, formatServerError } from "./shared";
+import { CommandUsageError, formatServerError, resolveProjectBaseUrl } from "./shared";
 
 export interface ParsedLinearPostCommand {
   branch: string;
@@ -126,8 +126,8 @@ export async function runLinearCommand(args: string[], port: number): Promise<nu
     return 0;
   }
 
-  const api = createApi(`http://localhost:${port}`);
   try {
+    const api = createApi(await resolveProjectBaseUrl(port));
     const response = await api.postWorktreeToLinear({
       params: { name: parsed.post.branch },
       body: { target: parsed.post.target },

bin/src/oneshot.ts

@@ -3,7 +3,18 @@ import { apiPaths, AgentsUiConversationEventSchema, createApi, parseLinearTarget
 import { createLinearIssue, fetchTeamByKey, type LinearIssue } from "../../backend/src/services/linear-service";
 import { buildSeedFromLinear, defaultSeedFromLinearDeps } from "../../backend/src/services/conversation-export-service";
 import { findDuplicateLinearIssue, polishLinearIssueTitle } from "../../backend/src/services/linear-title-service";
-import { CommandUsageError, formatServerError } from "./shared";
+import { CommandUsageError, formatServerError, resolveProjectBaseUrl } from "./shared";
+
+// The server serves each project under `/<prefix>`. `runOneshot` resolves the
+// scoped base once and stashes it here so every helper (api calls + the agents
+// WebSocket) targets the right project. Null → unscoped fallback (port only).
+let oneshotBaseUrl: string | null = null;
+function oneshotApi(port: number): ReturnType<typeof createApi> {
+  return createApi(oneshotBaseUrl ?? `http://localhost:${port}`);
+}
+function oneshotPathPrefix(): string {
+  return oneshotBaseUrl ? new URL(oneshotBaseUrl).pathname.replace(/\/$/, "") : "";
+}
 
 export interface ParsedOneshotCommand {
   branch: string | null;
@@ -404,7 +415,7 @@ function streamConversation(
 
   const connect = (): void => {
     if (closed) return;
-    const url = `ws://localhost:${port}${apiPaths.streamAgentsWorktreeConversation.replace(":name", encodeURIComponent(branch))}`;
+    const url = `ws://localhost:${port}${oneshotPathPrefix()}${apiPaths.streamAgentsWorktreeConversation.replace(":name", encodeURIComponent(branch))}`;
     const ws = new WebSocket(url);
     socket = ws;
     ws.addEventListener("open", () => {
@@ -499,7 +510,7 @@ function pollProjectState(
   },
   stderr: (line: string) => void,
 ): { stop: () => void } {
-  const api = createApi(`http://localhost:${port}`);
+  const api = oneshotApi(port);
   let stopped = false;
   let timer: ReturnType<typeof setTimeout> | null = null;
 
@@ -597,7 +608,7 @@ async function ensureWorktreeReady(
   port: number,
   stderr: (line: string) => void,
 ): Promise<{ ready: true; worktree: ProjectWorktreeSnapshot } | { ready: false }> {
-  const api = createApi(`http://localhost:${port}`);
+  const api = oneshotApi(port);
   const deadline = Date.now() + 60_000;
   while (Date.now() < deadline) {
     try {
@@ -643,7 +654,7 @@ function pollConversationHistory(
   port: number,
   state: ConversationPrintState,
 ): { stop: () => void } {
-  const api = createApi(`http://localhost:${port}`);
+  const api = oneshotApi(port);
   let stopped = false;
   let timer: ReturnType<typeof setTimeout> | null = null;
 
@@ -717,7 +728,13 @@ export async function runOneshot(parsed: ParsedOneshotCommand, port: number): Pr
     process.stderr.write(`${line}\n`);
   };
 
-  const api = createApi(`http://localhost:${port}`);
+  try {
+    oneshotBaseUrl = await resolveProjectBaseUrl(port);
+  } catch (error) {
+    stderr(`[${timestamp()}] [error] ${formatServerError(error, port)}`);
+    return 1;
+  }
+  const api = oneshotApi(port);
   let branch = parsed.branch;
   const body: CreateWorktreeRequest = { ...parsed.body };
   let fromLinearIssueId = parsed.fromLinearIssueId;

bin/src/shared.ts

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
-import { basename, join } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
+import { createApi } from "@webmux/api-contract";
 
 export interface RunResult {
   success: boolean;
@@ -69,3 +70,39 @@ export async function withServerConnection<T>(port: number, fn: () => Promise<T>
     throw new Error(formatServerError(error, port));
   }
 }
+
+/** Resolve a directory to its canonical project (git) root — the shared root
+ *  even from a linked worktree — matching the server's `projectRoot()`. Returns
+ *  null when the dir isn't a git work tree (or git is unavailable). */
+export function resolveProjectRoot(cwd: string = process.cwd()): string | null {
+  try {
+    const common = run("git", ["rev-parse", "--git-common-dir"], { cwd });
+    if (common.success) {
+      const commonDir = common.stdout.toString().trim();
+      if (commonDir) return dirname(resolve(cwd, commonDir));
+    }
+    const top = run("git", ["rev-parse", "--show-toplevel"], { cwd });
+    return top.success ? top.stdout.toString().trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Base URL for talking to the active project on the running server. The server
+ *  serves each project under `/<prefix>`, so a server-backed CLI command must
+ *  target `http://localhost:<port>/<prefix>` for the project at `projectDir`.
+ *  Falls back to the unscoped base when the project root can't be determined;
+ *  throws a CommandUsageError when the root resolves but isn't a served project. */
+export async function resolveProjectBaseUrl(port: number, projectDir: string = process.cwd()): Promise<string> {
+  const base = `http://localhost:${port}`;
+  const root = resolveProjectRoot(projectDir);
+  if (!root) return base;
+  const { projects } = await createApi(base).fetchProjects();
+  const match = projects.find((project) => project.path === root);
+  if (!match) {
+    throw new CommandUsageError(
+      `This project (${root}) isn't served by webmux on port ${port}. Run \`webmux project add\` or start \`webmux serve\` in it first.`,
+    );
+  }
+  return `${base}/${match.prefix}`;
+}

bin/src/webmux.ts

@@ -403,10 +403,9 @@ async function main(args: string[] = process.argv.slice(2)): Promise<void> {
     process.exit(0);
   }
 
-  if (!existsSync(resolve(process.cwd(), ".webmux.yaml"))) {
-    console.error("No .webmux.yaml found in this directory.\nRun `webmux init` to set up your project.");
-    process.exit(1);
-  }
+  // No `.webmux.yaml` requirement here: the server serves every known project
+  // (from ~/.webmux/projects.json) on one port and auto-adds the cwd repo when
+  // it is a webmux project. Running from a fresh dir just shows the empty state.
 
   const baseEnv = {
     ...process.env,

bin/src/worktree-commands.ts

@@ -2,7 +2,7 @@ import * as p from "@clack/prompts";
 import { createApi } from "@webmux/api-contract";
 import { basename, resolve } from "node:path";
 import { buildSeedFromLinear, defaultSeedFromLinearDeps } from "../../backend/src/services/conversation-export-service";
-import { CommandUsageError, withServerConnection } from "./shared";
+import { CommandUsageError, resolveProjectBaseUrl, withServerConnection } from "./shared";
 import { readWorktreeArchiveState, readWorktreeMeta } from "../../backend/src/adapters/fs";
 import { buildProjectSessionName, buildWorktreeWindowName } from "../../backend/src/adapters/tmux";
 import type { AgentId } from "../../backend/src/domain/config";
@@ -851,7 +851,7 @@ export async function runWorktreeCommand(
         return 0;
       }
 
-      const api = createApi(`http://localhost:${context.port}`);
+      const api = createApi(await withServerConnection(context.port, () => resolveProjectBaseUrl(context.port, context.projectDir)));
       await withServerConnection(context.port, () =>
         api.sendWorktreePrompt({
           params: { name: parsed.branch },
@@ -873,7 +873,7 @@ export async function runWorktreeCommand(
         return 0;
       }
 
-      const api = createApi(`http://localhost:${context.port}`);
+      const api = createApi(await withServerConnection(context.port, () => resolveProjectBaseUrl(context.port, context.projectDir)));
       await withServerConnection(context.port, async () => {
         if (parsed.action === "new") {
           const { tab } = await api.createWorktreeTab({ params: { name: parsed.branch } });