fix: restore agent status by prefixing the runtime control URL

Since #271 the server mounts every project's routes under `/${prefix}`,
but the agent hooks' control URL was built without the prefix, so status
events POSTed to `/api/runtime/events` fell through to the SPA and Claude's
status stopped updating.

- backend: thread the project prefix into the runtime's control base URL
  (buildControlBaseUrl + ProjectManager createRuntime), so hook events hit
  the project's prefixed `/api/runtime/events` route.
- cli: in-process add/open/refresh resolve the prefix best-effort from the
  running server (resolveProjectPrefix). When it can't be resolved (no
  server), no control URL is configured and no control.env is written —
  cleaner than a wrong, unrouted URL; status self-heals on next
  open/refresh from a dashboard.

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

Author: hugocasa

backend/src/__tests__/lifecycle-service.test.ts

@@ -284,6 +284,9 @@ function makeLifecycleService(
     onFinished?: (branch: string) => void | Promise<void>;
   } = {},
   sessionDiscovery: SessionDiscoveryGateway = { listSessionIds: async () => [] },
+  // `null` explicitly configures no control reporting (passing `undefined` would
+  // fall back to the default below).
+  controlBaseUrl: string | null = "http://127.0.0.1:5111",
 ): LifecycleService {
   const reconciliation = new ReconciliationService({
     config,
@@ -295,7 +298,7 @@ function makeLifecycleService(
 
   return new LifecycleService({
     projectRoot: repoRoot,
-    controlBaseUrl: "http://127.0.0.1:5111",
+    controlBaseUrl: controlBaseUrl ?? undefined,
     getControlToken: async () => "secret-token",
     config,
     archiveState: new ArchiveStateService(git.resolveWorktreeGitDir(repoRoot)),
@@ -407,6 +410,38 @@ describe("LifecycleService", () => {
     expect(state?.session.paneCount).toBe(2);
   });
 
+  it("writes no control.env when no control base URL is configured", async () => {
+    const repoRoot = await initRepo();
+    const runtime = new ProjectRuntime();
+    const tmux = new FakeTmuxGateway();
+    // The CLI leaves controlBaseUrl undefined when it can't resolve the project
+    // prefix (no server running). We'd rather write no control.env than one with
+    // a wrong (unrouted) URL — the dashboard rewrites it on next open/refresh.
+    const lifecycle = makeLifecycleService(
+      repoRoot,
+      tmux,
+      runtime,
+      new FakeDockerGateway(),
+      new FakeHookRunner(),
+      TEST_CONFIG,
+      new BunGitGateway(),
+      new FakeAutoNameService(),
+      {},
+      { listSessionIds: async () => [] },
+      null,
+    );
+
+    await lifecycle.createWorktree({ branch: "feature/search" });
+
+    const worktreePath = join(repoRoot, "__worktrees", "feature", "search");
+    const gitDir = new BunGitGateway().resolveWorktreeGitDir(worktreePath);
+    const paths = getWorktreeStoragePaths(gitDir);
+
+    expect(await Bun.file(paths.controlEnvPath).exists()).toBe(false);
+    // The runtime env (unrelated to control reporting) is still written.
+    expect(await Bun.file(paths.runtimeEnvPath).exists()).toBe(true);
+  });
+
   it("creates one managed worktree per selected agent from one task branch", async () => {
     const repoRoot = await initRepo();
     const runtime = new ProjectRuntime();

backend/src/__tests__/project-manager.test.ts

@@ -33,16 +33,19 @@ function makeManager(initial: ProjectEntry[] = []): {
   registry: ProjectsRegistry & { entries: ProjectEntry[] };
   loopCalls: Map<string, string[]>;
   createdFor: string[];
+  createdWith: Array<{ projectDir: string; port: number; prefix: string }>;
 } {
   const registry = fakeRegistry(initial);
   const loopCalls = new Map<string, string[]>();
   const createdFor: string[] = [];
+  const createdWith: Array<{ projectDir: string; port: number; prefix: string }> = [];
   const manager = new ProjectManager<FakeRuntime>({
     registry,
     port: 5111,
     resolveRoot: (path) => path,
-    createRuntime: ({ projectDir }) => {
+    createRuntime: ({ projectDir, port, prefix }) => {
       createdFor.push(projectDir);
+      createdWith.push({ projectDir, port, prefix });
       return { config: { name: `name:${projectDir}` } };
     },
     createLoops: (project: ManagedProject<FakeRuntime>): ProjectLoopController => {
@@ -56,7 +59,7 @@ function makeManager(initial: ProjectEntry[] = []): {
       };
     },
   });
-  return { manager, registry, loopCalls, createdFor };
+  return { manager, registry, loopCalls, createdFor, createdWith };
 }
 
 describe("ProjectManager", () => {
@@ -73,6 +76,18 @@ describe("ProjectManager", () => {
     expect(loopCalls.get("alpha")).toEqual(["startLight"]);
   });
 
+  it("passes the derived prefix to createRuntime so the runtime can build a prefixed control URL", () => {
+    const { manager, createdWith } = makeManager();
+
+    manager.add("/repo/alpha");
+    manager.add("/repo/alpha-clone/alpha");
+
+    expect(createdWith).toEqual([
+      { projectDir: "/repo/alpha", port: 5111, prefix: "alpha" },
+      { projectDir: "/repo/alpha-clone/alpha", port: 5111, prefix: "alpha-2" },
+    ]);
+  });
+
   it("addEphemeral serves the project in-memory but does not persist it", () => {
     const { manager, registry, loopCalls } = makeManager();
 

backend/src/__tests__/runtime-control-url.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "bun:test";
+import { buildControlBaseUrl } from "../runtime";
+
+// Regression: the server mounts every project's routes under `/${prefix}`
+// (see server.ts buildServeRoutes), so the control base URL that agent hooks
+// POST to must carry the same prefix or the events fall through to the SPA and
+// Claude's status never updates.
+describe("buildControlBaseUrl", () => {
+  it("includes the project prefix so it matches the prefixed server route", () => {
+    expect(buildControlBaseUrl(5111, "webmux")).toBe("http://127.0.0.1:5111/webmux");
+  });
+
+  it("keeps an unprefixed URL for an empty prefix (legacy single-project edge)", () => {
+    expect(buildControlBaseUrl(5111, "")).toBe("http://127.0.0.1:5111");
+  });
+
+  it("returns undefined when there is no prefix, disabling control reporting", () => {
+    // The CLI passes undefined when it can't resolve a prefix (no server
+    // running). No control URL is better than a wrong one: the agent's hooks
+    // no-op cleanly instead of POSTing to an unrouted path.
+    expect(buildControlBaseUrl(5111, undefined)).toBeUndefined();
+  });
+});

backend/src/runtime.ts

@@ -17,9 +17,26 @@ import { WorktreeCreationTracker } from "./services/worktree-creation-service";
 export interface WebmuxRuntimeOptions {
   projectDir?: string;
   port?: number;
+  /** URL-path prefix the server mounts this project's routes under. Agent hooks
+   *  POST status events to the control URL, which must carry the same prefix or
+   *  the events fall through to the SPA and Claude's status never updates. */
+  prefix?: string;
   onCreateProgress?: (progress: CreateWorktreeProgress) => void | Promise<void>;
 }
 
+/** Base URL agent hooks POST runtime events to. The server serves each project
+ *  under `/${prefix}` (see server.ts buildServeRoutes), so the control URL must
+ *  include the prefix to hit the project's `/api/runtime/events` route.
+ *
+ *  `undefined` prefix means control reporting is not configured (the CLI passes
+ *  it when it can't resolve a prefix — no server running). We return undefined
+ *  rather than an unprefixed URL so no control.env is written and the agent's
+ *  hooks no-op cleanly instead of POSTing to an unrouted path. */
+export function buildControlBaseUrl(port: number, prefix: string | undefined): string | undefined {
+  if (prefix === undefined) return undefined;
+  return prefix ? `http://127.0.0.1:${port}/${prefix}` : `http://127.0.0.1:${port}`;
+}
+
 export interface WebmuxRuntime {
   port: number;
   projectDir: string;
@@ -63,7 +80,7 @@ export function createWebmuxRuntime(options: WebmuxRuntimeOptions = {}): WebmuxR
   });
   const lifecycleService = new LifecycleService({
     projectRoot: projectDir,
-    controlBaseUrl: `http://127.0.0.1:${port}`,
+    controlBaseUrl: buildControlBaseUrl(port, options.prefix),
     getControlToken: loadControlToken,
     config,
     archiveState: archiveStateService,

backend/src/server.ts

@@ -2688,7 +2688,7 @@ BOUND_PORT = actualPort(server, PORT);
 manager = new ProjectManager({
   registry: createProjectsRegistry(),
   port: BOUND_PORT,
-  createRuntime: ({ projectDir, port }) => createWebmuxRuntime({ projectDir, port }),
+  createRuntime: ({ projectDir, port, prefix }) => createWebmuxRuntime({ projectDir, port, prefix }),
   createLoops: (project): ProjectLoopController => {
     const app = createProjectApp(project.runtime, project.prefix);
     apps.set(project.prefix, app);

backend/src/services/lifecycle-service.ts

@@ -19,7 +19,7 @@ import { type DockerGateway } from "../adapters/docker";
 import { buildProjectSessionName, buildWorktreeParkingWindowName, buildWorktreeWindowName, type TmuxGateway } from "../adapters/tmux";
 import { captureNewSessionId, type SessionDiscoveryGateway } from "../adapters/session-discovery";
 import type { AgentId, ProfileConfig, ProjectConfig, RuntimeKind } from "../domain/config";
-import { ROOT_TAB_ID, type OneshotMeta, type WorktreeCreationPhase, type WorktreeMeta, type WorktreeSource, type WorktreeTab } from "../domain/model";
+import { ROOT_TAB_ID, type ControlEnvMap, type OneshotMeta, type WorktreeCreationPhase, type WorktreeMeta, type WorktreeSource, type WorktreeTab } from "../domain/model";
 import {
   activeTabId as readActiveTabId,
   appendTab,
@@ -156,7 +156,9 @@ export interface CreateWorktreeProgress {
 
 export interface LifecycleServiceDependencies {
   projectRoot: string;
-  controlBaseUrl: string;
+  /** Absent when control reporting isn't configured (e.g. a CLI runtime that
+   *  couldn't resolve the project's route prefix). No control.env is written. */
+  controlBaseUrl?: string;
   getControlToken: () => Promise<string>;
   config: ProjectConfig;
   archiveState: ArchiveStateService;
@@ -976,8 +978,7 @@ export class LifecycleService {
       allocatedPorts: await this.allocatePorts(),
       runtimeEnvExtras: { WEBMUX_WORKTREE_PATH: resolved.entry.path },
       dotenvValues,
-      controlUrl: this.controlUrl(profile.runtime),
-      controlToken: await this.deps.getControlToken(),
+      ...(await this.controlEnvFields(profile.runtime)),
     });
   }
 
@@ -1006,13 +1007,17 @@ export class LifecycleService {
     }, dotenvValues);
     await writeRuntimeEnv(input.gitDir, runtimeEnv);
 
-    const controlEnv = buildControlEnvMap({
-      controlUrl: this.controlUrl(input.meta.runtime),
-      controlToken: await this.deps.getControlToken(),
-      worktreeId: input.meta.worktreeId,
-      branch: input.meta.branch,
-    });
-    await writeControlEnv(input.gitDir, controlEnv);
+    const controlUrl = this.controlUrl(input.meta.runtime);
+    let controlEnv: ControlEnvMap | null = null;
+    if (controlUrl) {
+      controlEnv = buildControlEnvMap({
+        controlUrl,
+        controlToken: await this.deps.getControlToken(),
+        worktreeId: input.meta.worktreeId,
+        branch: input.meta.branch,
+      });
+      await writeControlEnv(input.gitDir, controlEnv);
+    }
 
     return {
       meta: input.meta,
@@ -1241,10 +1246,20 @@ export class LifecycleService {
     }
   }
 
-  private controlUrl(runtime: RuntimeKind): string {
+  private controlUrl(runtime: RuntimeKind): string | undefined {
+    if (!this.deps.controlBaseUrl) return undefined;
     return `${buildRuntimeControlBaseUrl(this.deps.controlBaseUrl, runtime)}/api/runtime/events`;
   }
 
+  /** Control URL + token, paired so they're always both set or both absent
+   *  (initializeManagedWorktree rejects one without the other). Empty when
+   *  control reporting isn't configured. */
+  private async controlEnvFields(runtime: RuntimeKind): Promise<{ controlUrl?: string; controlToken?: string }> {
+    const controlUrl = this.controlUrl(runtime);
+    if (!controlUrl) return {};
+    return { controlUrl, controlToken: await this.deps.getControlToken() };
+  }
+
   private async removeResolvedWorktree(
     resolved: ResolvedLifecycleWorktree,
   ): Promise<void> {
@@ -1378,8 +1393,7 @@ export class LifecycleService {
           startupEnvValues: await this.buildStartupEnvValues(input.envOverrides),
           allocatedPorts: await this.allocatePorts(),
           runtimeEnvExtras: { WEBMUX_WORKTREE_PATH: worktreePath },
-          controlUrl: this.controlUrl(profile.runtime),
-          controlToken: await this.deps.getControlToken(),
+          ...(await this.controlEnvFields(profile.runtime)),
           deleteBranchOnRollback,
           source,
           ...(input.oneshot ? { oneshot: input.oneshot } : {}),

backend/src/services/project-manager.ts

@@ -43,7 +43,7 @@ export interface ProjectManagerDeps<R extends RuntimeLike = WebmuxRuntime> {
   port: number;
   /** Build the per-project runtime — pass `createWebmuxRuntime` in production.
    *  `R` is inferred from the return type, so tests can supply a typed stub. */
-  createRuntime: (options: { projectDir: string; port: number }) => R;
+  createRuntime: (options: { projectDir: string; port: number; prefix: string }) => R;
   /** Resolve an arbitrary path to its canonical project (git) root. */
   resolveRoot?: (path: string) => string;
   /** Build the loop controller for a project. Defaults to a no-op (wired in
@@ -58,7 +58,7 @@ export class ProjectManager<R extends RuntimeLike = WebmuxRuntime> {
   private readonly registry: ProjectsRegistry;
   private readonly port: number;
   private readonly resolveRoot: (path: string) => string;
-  private readonly createRuntime: (options: { projectDir: string; port: number }) => R;
+  private readonly createRuntime: (options: { projectDir: string; port: number; prefix: string }) => R;
   private readonly createLoops: (project: ManagedProject<R>) => ProjectLoopController;
   private readonly projects = new Map<string, ManagedProject<R>>();
   private readonly loops = new Map<string, ProjectLoopController>();
@@ -148,7 +148,7 @@ export class ProjectManager<R extends RuntimeLike = WebmuxRuntime> {
     }
 
     const prefix = deriveProjectPrefix(root, this.projects.keys());
-    const runtime = this.createRuntime({ projectDir: root, port: this.port });
+    const runtime = this.createRuntime({ projectDir: root, port: this.port, prefix });
     const entry: ProjectEntry = {
       path: root,
       name: runtime.config.name,

bin/src/shared.ts

@@ -96,3 +96,18 @@ export async function resolveProjectBaseUrl(port: number, projectDir: string = p
   }
   return `${base}/${match.prefix}`;
 }
+
+/** The server serves each project under `/<prefix>`, so an in-process runtime
+ *  that writes `control.env` must embed that prefix or the agent's status hooks
+ *  POST to an unrouted path. Best-effort: returns `undefined` when the prefix
+ *  can't be resolved (no server running, or the repo isn't a served project) so
+ *  the caller writes no control URL at all rather than a wrong one. Status
+ *  self-heals when the worktree is next opened/refreshed from a dashboard. */
+export async function resolveProjectPrefix(port: number, projectDir: string = process.cwd()): Promise<string | undefined> {
+  try {
+    const base = await resolveProjectBaseUrl(port, projectDir);
+    return new URL(base).pathname.replace(/^\/+|\/+$/g, "") || undefined;
+  } catch {
+    return undefined;
+  }
+}

bin/src/worktree-commands.test.ts

@@ -409,6 +409,32 @@ describe("runWorktreeCommand", () => {
     expect(stdout).toEqual(["Created worktree feature/remote-branch"]);
   });
 
+  it("passes the server-resolved project prefix to the runtime so control.env carries it", async () => {
+    const { runtime } = makeRuntime();
+    const createdWith: Array<{ prefix?: string }> = [];
+
+    const exitCode = await runWorktreeCommand(
+      {
+        command: "add",
+        args: ["feature/search", "--detach"],
+        projectDir: "/repo",
+        port: 5111,
+      },
+      {
+        createRuntime: (options) => {
+          createdWith.push({ prefix: options.prefix });
+          return runtime;
+        },
+        resolveProjectPrefix: async () => "myproject",
+        stdout: () => {},
+        switchToTmuxWindow: () => {},
+      },
+    );
+
+    expect(exitCode).toBe(0);
+    expect(createdWith).toEqual([{ prefix: "myproject" }]);
+  });
+
   it("skips tmux switch when --detach is passed to add", async () => {
     const { runtime } = makeRuntime();
     const stdout: string[] = [];