codehost 0.15.0 → 0.17.0

package/src/cli/plugins/agent-yes.ts

@@ -0,0 +1,116 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { toPosixPath } from "../../shared/repo";
+import type { AgentInfo } from "../../shared/signaling";
+import type { DaemonPlugin } from "./types";
+
+// agent-yes plugin: advertises the machine's live agent CLI sessions (read
+// straight from agent-yes's registry, so it works even when `ay serve` is
+// down) and proxies /__codehost/agent-yes/* to the local `ay serve` API with
+// its bearer token injected. Granting room members agent control is not new
+// trust: the room token already grants code execution (the editor is a
+// terminal) — same boundary as provisioning (see shared/provision.ts).
+
+const AY_DIR = join(homedir(), ".agent-yes");
+const AY_PORT = Number(process.env.CODEHOST_AY_PORT) || 7432;
+/** Cap the advertised list (meta rides the signaling room broadcast). */
+const MAX_AGENTS = 50;
+
+interface AyRecord {
+  pid: number;
+  cli?: string;
+  prompt?: string | null;
+  cwd?: string;
+  status?: "active" | "idle" | "exited";
+  started_at?: number;
+}
+
+/** agent-yes's global registry: JSONL, last line per pid wins. */
+export function readAgents(dir: string = AY_DIR): AgentInfo[] {
+  let raw: string;
+  try {
+    raw = readFileSync(join(dir, "pids.jsonl"), "utf8");
+  } catch {
+    return [];
+  }
+  const byPid = new Map<number, AyRecord>();
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const rec = JSON.parse(line) as AyRecord;
+      if (typeof rec.pid === "number") byPid.set(rec.pid, { ...byPid.get(rec.pid), ...rec });
+    } catch {
+      // skip malformed lines
+    }
+  }
+  const out: AgentInfo[] = [];
+  for (const rec of [...byPid.values()].sort((a, b) => (b.started_at ?? 0) - (a.started_at ?? 0))) {
+    if (out.length >= MAX_AGENTS) break;
+    if (rec.status === "exited" || !alive(rec.pid)) continue;
+    out.push({
+      pid: rec.pid,
+      tool: rec.cli || "agent",
+      ...(rec.prompt ? { title: rec.prompt.slice(0, 120) } : {}),
+      cwd: toPosixPath(rec.cwd ?? ""),
+      state: rec.status === "active" ? "active" : "idle",
+      ...(rec.started_at ? { startedAt: rec.started_at } : {}),
+    });
+  }
+  return out;
+}
+
+function alive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function serveToken(dir: string): string | null {
+  try {
+    const t = readFileSync(join(dir, ".serve-token"), "utf8").trim();
+    return t || null;
+  } catch {
+    return null;
+  }
+}
+
+/** The plugin, or null when this machine has never run agent-yes. */
+export function agentYesPlugin(dir: string = AY_DIR): DaemonPlugin | null {
+  if (!existsSync(dir)) return null;
+  return {
+    name: "agent-yes",
+    meta: () => {
+      const agents = readAgents(dir);
+      return agents.length > 0 ? { agents } : {};
+    },
+    route: async (path, req) => {
+      const token = serveToken(dir);
+      if (!token) {
+        return new Response(JSON.stringify({ error: "ay serve has no token (is agent-yes installed?)" }), {
+          status: 503,
+          headers: { "content-type": "application/json" },
+        });
+      }
+      const headers = new Headers(req.headers);
+      headers.set("authorization", `Bearer ${token}`);
+      headers.set("host", `127.0.0.1:${AY_PORT}`);
+      try {
+        return await fetch(`http://127.0.0.1:${AY_PORT}${path}`, {
+          method: req.method,
+          headers,
+          body: req.body as BodyInit | undefined,
+          redirect: "manual",
+        });
+      } catch {
+        return new Response(JSON.stringify({ error: "ay serve is not running (start it with `ay serve install`)" }), {
+          status: 502,
+          headers: { "content-type": "application/json" },
+        });
+      }
+    },
+  };
+}

package/src/cli/plugins/types.ts

@@ -0,0 +1,39 @@
+import type { PeerMeta } from "../../shared/signaling";
+
+// Daemon plugin surface: a plugin contributes (a) fields merged into the
+// advertised PeerMeta on every refresh, and (b) an HTTP route mounted under the
+// tunnel at /__codehost/<name>/*. codehost stays the transport + registry;
+// plugins (agent-yes first) own their domain.
+
+export interface DaemonPlugin {
+  /** Identifier; also the tunnel mount: requests to /__codehost/<name>/* land
+   *  in `route`. */
+  name: string;
+  /** Resource contribution, merged into PeerMeta by the daemon's meta builder
+   *  (startup + every refresh). Keep it small — it rides room broadcasts. */
+  meta?: () => Partial<PeerMeta>;
+  /** Serve a tunneled request. `path` is the remainder after the mount, always
+   *  starting with "/" and keeping the query string. */
+  route?: (path: string, req: { method: string; headers: Headers; body?: Uint8Array }) => Promise<Response>;
+}
+
+/** Route a local tunnel request to the owning plugin, or null to fall through. */
+export function routePlugins(
+  plugins: DaemonPlugin[],
+  req: { method: string; path: string; headers: Headers; body?: Uint8Array },
+): Promise<Response> | null {
+  for (const p of plugins) {
+    if (!p.route) continue;
+    const mount = `/__codehost/${p.name}`;
+    if (req.path === mount || req.path.startsWith(`${mount}/`) || req.path.startsWith(`${mount}?`)) {
+      const rest = req.path.slice(mount.length) || "/";
+      return p.route(rest.startsWith("/") ? rest : `/${rest}`, req);
+    }
+  }
+  return null;
+}
+
+/** Merge every plugin's meta contribution into a base meta. */
+export function withPluginMeta(base: PeerMeta, plugins: DaemonPlugin[]): PeerMeta {
+  return Object.assign({}, base, ...plugins.map((p) => p.meta?.() ?? {}));
+}

package/src/cli/provision-server.test.ts

@@ -0,0 +1,76 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { handleProvision, isProvisionPath } from "./provision-server";
+
+// A throwaway home with an optional .codehost/setup.sh.
+function makeHome(setup?: string, configYaml?: string): string {
+  const home = mkdtempSync(join(tmpdir(), "codehost-prov-"));
+  if (setup || configYaml) mkdirSync(join(home, ".codehost"), { recursive: true });
+  if (setup) writeFileSync(join(home, ".codehost", "setup.sh"), setup);
+  if (configYaml) writeFileSync(join(home, ".codehost", "config.yaml"), configYaml);
+  homes.push(home);
+  return home;
+}
+const homes: string[] = [];
+afterAll(() => homes.forEach((h) => rmSync(h, { recursive: true, force: true })));
+
+const q = (owner: string, repo: string, branch = "main") =>
+  `/__codehost/provision?owner=${owner}&repo=${repo}&branch=${branch}`;
+
+describe("isProvisionPath", () => {
+  test("matches the route, ignores query + other paths", () => {
+    expect(isProvisionPath("/__codehost/provision?owner=a")).toBe(true);
+    expect(isProvisionPath("/vs/abc/?folder=x")).toBe(false);
+  });
+});
+
+describe("handleProvision", () => {
+  test("no setup script → 200 + workspace path in header/body (today's behavior)", async () => {
+    const home = makeHome();
+    const res = await handleProvision(q("snomiao", "codehost"), { homeDir: home, host: "github.com" });
+    expect(res.status).toBe(200);
+    expect(res.headers.get("x-codehost-workspace")).toBe(`${home}/snomiao/codehost/tree/main`);
+    expect(await res.json()).toEqual({ workspace: `${home}/snomiao/codehost/tree/main` });
+  });
+
+  test("runs setup.sh, streams output + exit sentinel, env is passed", async () => {
+    const home = makeHome('echo "owner=$CODEHOST_OWNER branch=$CODEHOST_BRANCH ws=$CODEHOST_WS"\nexit 0\n');
+    const res = await handleProvision(q("snomiao", "codehost", "feat/x"), { homeDir: home, host: "github.com" });
+    expect(res.status).toBe(200);
+    expect(res.headers.get("x-codehost-workspace")).toBe(`${home}/snomiao/codehost/tree/feat/x`);
+    const body = await res.text();
+    expect(body).toContain(`owner=snomiao branch=feat/x ws=${home}/snomiao/codehost/tree/feat/x`);
+    expect(body).toContain("::codehost:exit=0");
+  });
+
+  test("propagates a non-zero exit code in the sentinel", async () => {
+    const home = makeHome('echo "boom" >&2\nexit 7\n');
+    const res = await handleProvision(q("snomiao", "codehost"), { homeDir: home, host: "github.com" });
+    const body = await res.text();
+    expect(body).toContain("boom");
+    expect(body).toContain("::codehost:exit=7");
+  });
+
+  test("rejects a traversal identity with 400 (no spawn)", async () => {
+    const home = makeHome("echo SHOULD_NOT_RUN\nexit 0\n");
+    const res = await handleProvision(q("..", "codehost"), { homeDir: home, host: "github.com" });
+    expect(res.status).toBe(400);
+    expect(await res.text()).not.toContain("SHOULD_NOT_RUN");
+  });
+
+  test("enforces the config allowlist with 403", async () => {
+    const home = makeHome("echo hi\nexit 0\n", "allowlist:\n  - github.com/snomiao/*\n");
+    const ok = await handleProvision(q("snomiao", "codehost"), { homeDir: home, host: "github.com" });
+    expect(ok.status).toBe(200);
+    const denied = await handleProvision(q("evil", "repo"), { homeDir: home, host: "github.com" });
+    expect(denied.status).toBe(403);
+  });
+
+  test("config.yaml workspace template overrides the layout", async () => {
+    const home = makeHome(undefined, 'workspace: "ws/{owner}/{repo}/tree/{branch}"\n');
+    const res = await handleProvision(q("snomiao", "codehost"), { homeDir: home, host: "github.com" });
+    expect(res.headers.get("x-codehost-workspace")).toBe(`${home}/ws/snomiao/codehost/tree/main`);
+  });
+});

package/src/cli/provision-server.ts

@@ -0,0 +1,186 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { repoAllowed, resolveWorkspacePath, validateProvisionTarget, type ProvisionTarget } from "../shared/provision";
+import { fromPosixPath, repoKey, toPosixPath } from "../shared/repo";
+
+// Daemon side of provisioning. A repo open hits `GET /__codehost/provision?...`
+// over the tunnel; this validates the identity, computes the daemon-authoritative
+// workspace path, and (if `.codehost/setup.sh` exists) runs it, streaming its
+// output back as the response body. The resolved path rides in the
+// `x-codehost-workspace` header so it never depends on parsing script output.
+
+export const PROVISION_PATH = "/__codehost/provision";
+const TIMEOUT_MS = Number(process.env.CODEHOST_PROVISION_TIMEOUT_MS) || 15 * 60_000;
+
+export interface ProvisionDeps {
+  /** Real OS path of the served home root. */
+  homeDir: string;
+  /** Git host advertised by this daemon (default github.com). */
+  host: string;
+  /** Called after a setup script finishes (any exit code) — lets the daemon
+   *  re-enumerate + re-advertise its workspaces. */
+  onProvisioned?: () => void;
+}
+
+export interface CodehostConfig {
+  workspace?: string; // layout template, e.g. "ws/{owner}/{repo}/tree/{branch}"
+  allowlist?: string[];
+}
+
+/** True for the provision route (ignoring the query string). */
+export function isProvisionPath(path: string): boolean {
+  return path.split("?")[0] === PROVISION_PATH;
+}
+
+export function readCodehostConfig(homeDir: string): CodehostConfig {
+  try {
+    const raw = readFileSync(join(homeDir, ".codehost", "config.yaml"), "utf8");
+    const c = (parseYaml(raw) ?? {}) as Record<string, unknown>;
+    return {
+      workspace: typeof c.workspace === "string" ? c.workspace : undefined,
+      allowlist: Array.isArray(c.allowlist)
+        ? c.allowlist.filter((x): x is string => typeof x === "string")
+        : undefined,
+    };
+  } catch {
+    return {};
+  }
+}
+
+/** Locate the host's setup script (platform-appropriate), or null if none — in
+ *  which case provisioning is a no-op and we just return the path. */
+function findSetupScript(homeDir: string): string[] | null {
+  const dir = join(homeDir, ".codehost");
+  if (process.platform === "win32") {
+    const bat = join(dir, "setup.bat");
+    if (existsSync(bat)) return ["cmd", "/c", bat];
+    const ps1 = join(dir, "setup.ps1");
+    if (existsSync(ps1)) return ["powershell", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", ps1];
+  }
+  const sh = join(dir, "setup.sh");
+  if (existsSync(sh)) return ["bash", sh];
+  return null;
+}
+
+// Per-workspace coalescing: a concurrent open of the same target waits for the
+// running provision instead of spawning a second one.
+const inFlight = new Map<string, Promise<number>>();
+
+export async function handleProvision(rawPath: string, deps: ProvisionDeps): Promise<Response> {
+  const url = new URL(`http://x${rawPath}`);
+  const v = validateProvisionTarget(
+    url.searchParams.get("owner") ?? "",
+    url.searchParams.get("repo") ?? "",
+    url.searchParams.get("branch") ?? "",
+  );
+  if (!v.ok) return json(400, { error: v.reason });
+
+  const host = (url.searchParams.get("host") ?? deps.host).toLowerCase();
+  const cfg = readCodehostConfig(deps.homeDir);
+  const key = repoKey({ host, owner: v.target.owner, name: v.target.repo });
+  if (!repoAllowed(key, cfg.allowlist)) return json(403, { error: `repo not allowlisted: ${key}` });
+
+  const wsPosix = resolveWorkspacePath(toPosixPath(deps.homeDir), cfg.workspace ?? "", v.target);
+  const headers = { "x-codehost-workspace": wsPosix };
+
+  const cmd = findSetupScript(deps.homeDir);
+  if (!cmd) return json(200, { workspace: wsPosix }, headers); // no script: hand back the path
+
+  const lockKey = fromPosixPath(wsPosix);
+  const existing = inFlight.get(lockKey);
+  const body = existing
+    ? coalescedBody(existing) // a provision is already running for this workspace
+    : freshBody(cmd, deps, v.target, host, lockKey);
+  return new Response(body, {
+    status: 200,
+    headers: { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store", ...headers },
+  });
+}
+
+/** Spawn the setup script, streaming merged stdout+stderr, ending with an exit
+ *  sentinel the browser parses for success/failure. */
+function freshBody(
+  cmd: string[],
+  deps: ProvisionDeps,
+  target: ProvisionTarget,
+  host: string,
+  lockKey: string,
+): ReadableStream<Uint8Array> {
+  const enc = new TextEncoder();
+  return new ReadableStream<Uint8Array>({
+    async start(controller) {
+      let resolveDone!: (code: number) => void;
+      inFlight.set(lockKey, new Promise<number>((r) => (resolveDone = r)));
+      const say = (s: string) => controller.enqueue(enc.encode(s));
+      say(`[codehost] provisioning ${host}/${target.owner}/${target.repo}@${target.branch}\n`);
+      let code = 1;
+      try {
+        const proc = Bun.spawn(cmd, {
+          cwd: deps.homeDir,
+          env: {
+            ...process.env,
+            CODEHOST_OWNER: target.owner,
+            CODEHOST_REPO: target.repo,
+            CODEHOST_BRANCH: target.branch,
+            CODEHOST_HOST: host,
+            CODEHOST_HOME: deps.homeDir,
+            CODEHOST_WS: fromPosixPath(lockKey),
+          },
+          stdout: "pipe",
+          stderr: "pipe",
+        });
+        const timer = setTimeout(() => {
+          try {
+            proc.kill();
+          } catch {
+            // already gone
+          }
+        }, TIMEOUT_MS);
+        const pump = async (stream: ReadableStream<Uint8Array>) => {
+          const reader = stream.getReader();
+          for (;;) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            controller.enqueue(value);
+          }
+        };
+        await Promise.all([pump(proc.stdout), pump(proc.stderr)]);
+        code = await proc.exited;
+        clearTimeout(timer);
+      } catch (err) {
+        say(`[codehost] provision error: ${String(err)}\n`);
+      } finally {
+        inFlight.delete(lockKey);
+        resolveDone(code);
+        say(`\n::codehost:exit=${code}\n`);
+        controller.close();
+        try {
+          deps.onProvisioned?.();
+        } catch {
+          // advertising is best-effort; never fail the provision response
+        }
+      }
+    },
+  });
+}
+
+/** Attach to a running provision: wait for it, then emit the exit sentinel. */
+function coalescedBody(existing: Promise<number>): ReadableStream<Uint8Array> {
+  const enc = new TextEncoder();
+  return new ReadableStream<Uint8Array>({
+    async start(controller) {
+      controller.enqueue(enc.encode("[codehost] provision already running for this workspace; waiting…\n"));
+      const code = await existing.catch(() => 1);
+      controller.enqueue(enc.encode(`\n::codehost:exit=${code}\n`));
+      controller.close();
+    },
+  });
+}
+
+function json(status: number, obj: unknown, extra: Record<string, string> = {}): Response {
+  return new Response(JSON.stringify(obj), {
+    status,
+    headers: { "content-type": "application/json", "cache-control": "no-store", ...extra },
+  });
+}

package/src/cli/registry.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  clearDaemonPresence,
+  liveDaemon,
+  readRegisteredWorkspaces,
+  registerWorkspace,
+  writeDaemonPresence,
+} from "./registry";
+
+const tmp = () => mkdtempSync(join(tmpdir(), "codehost-registry-"));
+
+describe("daemon presence", () => {
+  test("round-trips while the pid is alive; cleared file -> null", () => {
+    const file = join(tmp(), "daemon.json");
+    const p = { pid: process.pid, root: "/Users/x", token: "Str0ng-Token-99", startedAt: 1 };
+    writeDaemonPresence(p, file);
+    expect(liveDaemon(file)).toEqual(p);
+    clearDaemonPresence(file);
+    expect(liveDaemon(file)).toBeNull();
+  });
+
+  test("a dead pid (stale kill -9 leftover) reads as no daemon", () => {
+    const file = join(tmp(), "daemon.json");
+    writeDaemonPresence({ pid: 99999999, root: "/x", token: "t0k-En-Stronk", startedAt: 1 }, file);
+    expect(liveDaemon(file)).toBeNull();
+  });
+
+  test("garbage file reads as no daemon", () => {
+    const file = join(tmp(), "daemon.json");
+    writeFileSync(file, "not json");
+    expect(liveDaemon(file)).toBeNull();
+  });
+});
+
+describe("workspace registry", () => {
+  test("register is idempotent; missing dirs are filtered on read", () => {
+    const dir = tmp();
+    const file = join(dir, "workspaces.json");
+    const ws = join(dir, "proj");
+    mkdirSync(ws);
+    registerWorkspace(ws, file);
+    registerWorkspace(ws, file);
+    registerWorkspace(join(dir, "gone"), file); // never created on disk
+    const got = readRegisteredWorkspaces(file);
+    expect(got).toHaveLength(1);
+    expect(got[0].path).toBe(ws);
+  });
+});

package/src/cli/registry.ts

@@ -0,0 +1,93 @@
+import { existsSync, readFileSync, rmSync, statSync, writeFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+// One-daemon-per-host coordination (Phase 5 of the resource-model redesign).
+// A single VS Code serve-web opens ANY local path via ?folder=, so one root
+// daemon can carry every workspace on the machine: a later `codehost dev`
+// REGISTERS its directory here and exits instead of spawning a second peer +
+// VS Code. The daemon advertises registered dirs in meta.workspaces and
+// re-reads this registry on fs.watch + the slow refresh tick.
+
+export const CODEHOST_DIR = join(homedir(), ".codehost");
+const DAEMON_FILE = join(CODEHOST_DIR, "daemon.json");
+const WORKSPACES_FILE = join(CODEHOST_DIR, "workspaces.json");
+
+/** Written by a foreground root daemon while it runs; staleness is detected by
+ *  pid liveness, so a kill -9 leftover never blocks anything. */
+export interface DaemonPresence {
+  pid: number;
+  /** Real OS path of the served root. */
+  root: string;
+  /** Room token the daemon registered with — later `dev` runs print a link
+   *  into THIS room, since that's where the workspace will appear. */
+  token: string;
+  startedAt: number;
+}
+
+export interface RegisteredWorkspace {
+  /** Real OS path. */
+  path: string;
+  addedAt: number;
+}
+
+export function writeDaemonPresence(p: DaemonPresence, file: string = DAEMON_FILE): void {
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(p, null, 2));
+}
+
+export function clearDaemonPresence(file: string = DAEMON_FILE): void {
+  try {
+    rmSync(file);
+  } catch {
+    // already gone
+  }
+}
+
+/** The live host daemon, or null (no file, unparsable, or its pid is dead). */
+export function liveDaemon(file: string = DAEMON_FILE): DaemonPresence | null {
+  try {
+    const p = JSON.parse(readFileSync(file, "utf8")) as DaemonPresence;
+    if (typeof p.pid !== "number" || !p.root || !p.token) return null;
+    process.kill(p.pid, 0);
+    return p;
+  } catch {
+    return null;
+  }
+}
+
+/** Add a directory to the host's workspace registry (idempotent). */
+export function registerWorkspace(path: string, file: string = WORKSPACES_FILE): void {
+  const dir = resolve(path);
+  const all = readRegistry(file);
+  if (all.some((w) => w.path === dir)) return;
+  all.push({ path: dir, addedAt: Date.now() });
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(all, null, 2));
+}
+
+/** Registered workspaces whose directories still exist. */
+export function readRegisteredWorkspaces(file: string = WORKSPACES_FILE): RegisteredWorkspace[] {
+  return readRegistry(file).filter((w) => {
+    try {
+      return statSync(w.path).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+}
+
+/** The registry path — daemons fs.watch its directory for instant re-advertise. */
+export function workspacesFile(): string {
+  return WORKSPACES_FILE;
+}
+
+function readRegistry(file: string): RegisteredWorkspace[] {
+  try {
+    if (!existsSync(file)) return [];
+    const arr = JSON.parse(readFileSync(file, "utf8"));
+    return Array.isArray(arr) ? arr.filter((w) => w && typeof w.path === "string") : [];
+  } catch {
+    return [];
+  }
+}

package/src/cli/run-server.ts

@@ -1,7 +1,11 @@
+import { watch } from "node:fs";
+import { basename, dirname } from "node:path";
 import { type PeerMeta, newPeerId } from "../shared/signaling";
 import { SignalingClient } from "../shared/signaling-client";
 import { RtcDaemon } from "./rtc-daemon";
-import { Tunnel } from "./tunnel";
+import { type LocalRequest, Tunnel } from "./tunnel";
+import { handleProvision, isProvisionPath, type ProvisionDeps } from "./provision-server";
+import { type DaemonPlugin, routePlugins } from "./plugins/types";
 
 export interface LaunchResult {
   /** Local port to tunnel to. */
@@ -24,8 +28,25 @@ export interface RunServerOptions {
   label: string;
   /** Prepare the local target to tunnel, given the /vs/<peerId> base path. */
   launch: (basePath: string) => Promise<LaunchResult>;
+  /** Enables `/__codehost/provision` on the tunnel (serve only — runs the home's
+   *  setup.sh). Omitted by `expose`, which has no home/workspace. */
+  provision?: ProvisionDeps;
+  /** Recompute the advertised meta (e.g. re-enumerate workspaces). Polled on a
+   *  slow interval and right after each provision; pushed to the room only when
+   *  it actually changed. */
+  refreshMeta?: () => PeerMeta;
+  /** Daemon plugins: tunneled routes under /__codehost/<name>/ (their meta
+   *  contributions are the caller's job, inside `meta`/`refreshMeta`). */
+  plugins?: DaemonPlugin[];
+  /** Files whose change should trigger an immediate `refreshMeta` (e.g. the
+   *  host workspace registry). Watched via their parent directory so the file
+   *  may not exist yet. */
+  watchFiles?: string[];
 }
 
+/** How often a daemon re-enumerates its workspaces (manual clones show up). */
+const META_REFRESH_MS = 60_000;
+
 /**
  * Foreground server loop shared by `serve`, `dev`, and `expose`: register in the
  * signaling room with the given meta and bridge each viewer's data channel to a
@@ -60,15 +81,54 @@ export async function runServer(opts: RunServerOptions): Promise<never> {
     onSignal: (from, data) => rtc.handleSignal(from, data),
   });
 
+  // Re-advertise when the workspace set changes (provision, manual clone).
+  let lastMeta = JSON.stringify(opts.meta);
+  const refreshMeta = () => {
+    if (!opts.refreshMeta) return;
+    const meta = opts.refreshMeta();
+    const s = JSON.stringify(meta);
+    if (s === lastMeta) return;
+    lastMeta = s;
+    client.updateMeta(meta);
+  };
+  const provision: ProvisionDeps | undefined = opts.provision
+    ? { ...opts.provision, onProvisioned: refreshMeta }
+    : undefined;
+  const plugins = opts.plugins ?? [];
+  const onLocal =
+    provision || plugins.length > 0
+      ? (req: LocalRequest) => {
+          if (provision && isProvisionPath(req.path)) return handleProvision(req.path, provision);
+          return routePlugins(plugins, req);
+        }
+      : undefined;
+
   rtc = new RtcDaemon({
     sendSignal: (to, data) => client.sendSignal(to, data),
     onChannel: (viewerId, channel) => {
       console.log(`[codehost] viewer ${viewerId.slice(0, 8)} connected; bridging to :${target.port}`);
-      new Tunnel(channel, target.port, target.stripBasePath);
+      new Tunnel(channel, target.port, target.stripBasePath, onLocal);
     },
   });
 
   client.connect();
+  if (opts.refreshMeta) {
+    setInterval(refreshMeta, META_REFRESH_MS);
+    // Instant re-advertise when a watched file changes (debounced — editors
+    // and fs.watch both fire in bursts).
+    let pending: ReturnType<typeof setTimeout> | null = null;
+    for (const file of opts.watchFiles ?? []) {
+      try {
+        watch(dirname(file), (_event, filename) => {
+          if (filename && filename !== basename(file)) return;
+          if (pending) clearTimeout(pending);
+          pending = setTimeout(refreshMeta, 300);
+        });
+      } catch {
+        // missing dir / unsupported platform — the interval still covers it
+      }
+    }
+  }
 
   const shutdown = () => {
     console.log("\n[codehost] shutting down");