zooid 0.7.3 → 0.8.0

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   buildAcpRegistry
-} from "./chunk-3IKBBKGI.js";
+} from "./chunk-R6EDLH23.js";
 export {
   buildAcpRegistry
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zooid",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "description": "Open-source tool for defining and running AI agents alongside you and your team. Any model, any CLI.",
   "type": "module",
   "license": "MIT",
@@ -24,6 +24,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "zooid": {
+    "zoonWebVersion": "0.1.0"
+  },
   "engines": {
     "node": ">=22"
   },
@@ -36,14 +39,15 @@
     "listr2": "^8.2.5",
     "marked": "^18.0.4",
     "sanitize-html": "^2.17.4",
+    "tar": "^7.5.16",
     "yaml": "^2.5.0",
-    "@zooid/context-mcp": "^0.7.3",
-    "@zooid/acp-client": "^0.7.3",
-    "@zooid/transport-http": "^0.7.3",
-    "@zooid/runtime-docker": "^0.7.3",
-    "@zooid/transport-matrix": "^0.7.3",
-    "@zooid/runtime-local": "^0.7.3",
-    "@zooid/core": "^0.7.3"
+    "@zooid/context-mcp": "^0.8.0",
+    "@zooid/core": "^0.8.0",
+    "@zooid/acp-client": "^0.8.0",
+    "@zooid/transport-http": "^0.8.0",
+    "@zooid/transport-matrix": "^0.8.0",
+    "@zooid/runtime-docker": "^0.8.0",
+    "@zooid/runtime-local": "^0.8.0"
   },
   "devDependencies": {
     "@agentclientprotocol/sdk": "^0.21.0",

package/src/bin.ts

@@ -33,7 +33,7 @@ cli
   .option('--admin-password <pw>', 'Admin password', { default: 'admin' })
   .option(
     '--watch-web [path]',
-    'Run vite build --watch on @zoon/web. Path defaults to sibling ../zoon/packages/web.',
+    'Run vite build --watch on @zooid/zoon-web. Path defaults to sibling ../zoon/packages/web.',
   )
   .action(async (flags) => {
     await runDev({

package/src/commands/dev.ts

@@ -1,7 +1,7 @@
 import chalk from 'chalk'
 import { Listr } from 'listr2'
 import { existsSync, readFileSync } from 'node:fs'
-import { dirname, resolve } from 'node:path'
+import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { serve, type ServerType } from '@hono/node-server'
 import {
@@ -17,7 +17,8 @@ import { resolvePaths } from '../bootstrap/paths.js'
 import { ensureTokens, type Tokens } from '../bootstrap/tokens.js'
 import { startDaemon, type DaemonHandle } from '../daemon/start-daemon.js'
 import { TuwunelService } from '../services/tuwunel.js'
-import { resolveWebRoot, webSourcePackage } from '../web/resolve.js'
+import { ensureWebRoot, webSourcePackage } from '../web/resolve.js'
+import { readZoonWebPin } from '../web/pin.js'
 import { webStatic } from '../web/static.js'
 import { startWebWatch, type WebWatchHandle } from '../web/watch.js'
 import {
@@ -66,7 +67,7 @@ export interface DevFlags {
   adminPassword: string
   installSignalHandlers?: boolean
   foreground?: boolean
-  // Run `vite build --watch` against a @zoon/web package and serve its dist.
+  // Run `vite build --watch` against a @zooid/zoon-web package and serve its dist.
   // true = auto-detect (sibling ../zoon/packages/web or in-monorepo); string = explicit path.
   watchWeb?: string | boolean
 }
@@ -202,6 +203,10 @@ export async function runDev(flags: DevFlags): Promise<DevHandle> {
             installSignalHandlers: false,
             adminUserId: `@${flags.adminUser}:${shape.serverName}`,
             agentsDir: layout.agentsDir,
+            // Local-only homeserver: make the workforce space publicly joinable
+            // so a self-service-registered dev account lands in #<space> from
+            // the web client without needing an invite.
+            publicWorkforceSpace: true,
             onTap: (agentName, event) => captures[agentName]?.onTap(event),
             prepullLog: (line) => {
               t.output = line.replace(/^\[zooid\]\s+/, '').trim()
@@ -212,7 +217,7 @@ export async function runDev(flags: DevFlags): Promise<DevHandle> {
       ...(flags.watchWeb
         ? [
             {
-              title: 'Start @zoon/web watcher (vite build --watch)',
+              title: 'Start @zooid/zoon-web watcher (vite build --watch)',
               task: async (): Promise<void> => {
                 const pkgDir =
                   typeof flags.watchWeb === 'string'
@@ -221,7 +226,7 @@ export async function runDev(flags: DevFlags): Promise<DevHandle> {
                 if (!pkgDir) {
                   const defaultPath = dirname(dirname(dirname(CLI_ROOT))) + '/zoon/packages/web'
                   throw new Error(
-                    `--watch-web: @zoon/web not found at ${defaultPath}.\n` +
+                    `--watch-web: @zooid/zoon-web not found at ${defaultPath}.\n` +
                       `Pass an explicit path: --watch-web=/path/to/zoon/packages/web`,
                   )
                 }
@@ -231,9 +236,18 @@ export async function runDev(flags: DevFlags): Promise<DevHandle> {
           ]
         : []),
       {
-        title: `Serve @zoon/web on http://localhost:${flags.uiPort}`,
-        task: () => {
-          const webRoot = ctx.webWatch?.distPath ?? resolveWebRoot(CLI_ROOT)
+        title: `Serve @zooid/zoon-web on http://localhost:${flags.uiPort}`,
+        task: async (_, t) => {
+          const webRoot =
+            ctx.webWatch?.distPath ??
+            (await ensureWebRoot({
+              cliRoot: CLI_ROOT,
+              cacheDir: join(layout.dataRoot, 'web'),
+              version: readZoonWebPin(CLI_ROOT),
+              onProgress: (msg) => {
+                t.output = msg
+              },
+            }))
           const app = webStatic({ webRoot, homeserverUrl: homeserver })
           ctx.uiServer = serve({ fetch: app.fetch, port: flags.uiPort })
         },
@@ -290,7 +304,7 @@ export async function runDev(flags: DevFlags): Promise<DevHandle> {
       `  ${chalk.cyan('admin user:')} ${flags.adminUser} / ${flags.adminPassword}`,
       `  ${chalk.cyan('data dir:')} ${layout.dataRoot}`,
       ...(ctx.webWatch
-        ? [`  ${chalk.cyan('web watcher:')} live (vite build --watch on @zoon/web)`]
+        ? [`  ${chalk.cyan('web watcher:')} live (vite build --watch on @zooid/zoon-web)`]
         : []),
       '',
       chalk.dim('Press Ctrl-C to stop.'),

package/src/daemon/start-daemon.ts

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs'
 import { mkdir, unlink } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
-import { dirname, join } from 'node:path'
+import { dirname, isAbsolute, join, resolve } from 'node:path'
 import type { AddressInfo } from 'node:net'
 import { serve, type ServerType } from '@hono/node-server'
 import {
@@ -17,6 +17,7 @@ import {
 import { createApp } from '@zooid/transport-http'
 import {
   MatrixClient,
+  MediaClient,
   createMatrixTransport,
   ensureDefaultChannel,
   ensureWorkforceSpace,
@@ -51,6 +52,13 @@ export interface StartDaemonOpts {
   noPrepull?: boolean
   /** Force a re-pull of every resolved image at startup (no inspect check). */
   refreshImages?: boolean
+  /**
+   * Create the workforce space publicly joinable instead of invite-only. Set
+   * only by `zooid dev`: the local homeserver is never deployed, so a
+   * self-service-registered account can join `#<space>` from the web client
+   * without an invite. Production (`zooid start`) leaves this off.
+   */
+  publicWorkforceSpace?: boolean
   /**
    * Per-line progress hook for the image-prepull pass. Called once per
    * top-level summary plus once per image (start + completion). Used by
@@ -155,6 +163,11 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
       homeserver: matrix.transport.homeserver,
       asToken: matrix.transport.as_token,
     })
+    const mediaClient = new MediaClient({
+      homeserver: matrix.transport.homeserver,
+      asToken: matrix.transport.as_token,
+    })
+    const isContainerRuntime = config.runtime !== 'local'
     const bindings: AgentBinding[] = []
     for (const a of Object.values(config.agents)) {
       if (a.matrix?.transport !== matrix.name) continue
@@ -165,6 +178,10 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
         trigger: a.matrix.trigger,
       }
       if (a.matrix.display_name !== undefined) binding.displayName = a.matrix.display_name
+      // Resolve workspace dirs for media attachment routing.
+      const workspaceDir = isAbsolute(a.workdir) ? a.workdir : resolve(configDir, a.workdir)
+      binding.workspaceDir = workspaceDir
+      binding.agentWorkspacePath = isContainerRuntime ? '/workspace' : workspaceDir
       bindings.push(binding)
     }
     const transport = createMatrixTransport({
@@ -174,6 +191,7 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
       bindings,
       hsToken: matrix.transport.hs_token,
       adminUserId: opts.adminUserId,
+      media: mediaClient,
     })
     const requestedPort = matrix.transport.port ?? 9000
     // Bind 0.0.0.0 explicitly — @hono/node-server defaults to IPv6-only on
@@ -200,6 +218,7 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
         spaceLocalpart,
         preset: 'public_chat',
         admins: adminUserIds,
+        joinRule: opts.publicWorkforceSpace ? 'public' : 'invite',
       })
       console.log(`[matrix] ensured workforce space #${spaceLocalpart}:${serverName} → ${spaceRoomId}`)
     } catch (err) {

package/src/web/fetch.integration.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest'
+import { createServer, type Server } from 'node:http'
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { type AddressInfo } from 'node:net'
+import { fetchWebBundle } from './fetch.js'
+import { makeBundleTgz } from './test-helpers.js'
+
+let server: Server
+let base = ''
+const { tgz, integrity } = makeBundleTgz({
+  'package/package.json': '{"name":"@zooid/zoon-web"}',
+  'package/dist/index.html': '<html>integration</html>',
+})
+
+beforeAll(async () => {
+  server = createServer((req, res) => {
+    if (req.url === '/@zooid/zoon-web') {
+      res.setHeader('content-type', 'application/json')
+      res.end(
+        JSON.stringify({
+          versions: {
+            '0.1.0': {
+              dist: { tarball: `${base}/@zooid/zoon-web/-/zoon-web-0.1.0.tgz`, integrity },
+            },
+          },
+        }),
+      )
+      return
+    }
+    if (req.url === '/@zooid/zoon-web/-/zoon-web-0.1.0.tgz') {
+      res.setHeader('content-type', 'application/octet-stream')
+      res.end(tgz)
+      return
+    }
+    res.statusCode = 404
+    res.end()
+  })
+  await new Promise<void>((r) => server.listen(0, '127.0.0.1', r))
+  base = `http://127.0.0.1:${(server.address() as AddressInfo).port}`
+})
+
+afterAll(() => new Promise<void>((r) => server.close(() => r())))
+
+describe('fetchWebBundle over real HTTP', () => {
+  it('fetches, verifies, extracts, and serves from cache on rerun', async () => {
+    const cacheDir = mkdtempSync(join(tmpdir(), 'zooid-webint-'))
+    try {
+      const root = await fetchWebBundle({ version: '0.1.0', cacheDir, registryUrl: base })
+      expect(readFileSync(join(root, 'index.html'), 'utf8')).toBe('<html>integration</html>')
+
+      const serverPort = (server.address() as AddressInfo).port
+      const newBase = `http://127.0.0.1:${serverPort}`
+      const again = await fetchWebBundle({ version: '0.1.0', cacheDir, registryUrl: newBase })
+      expect(again).toBe(root)
+    } finally {
+      rmSync(cacheDir, { recursive: true, force: true })
+    }
+  }, 30_000)
+})

package/src/web/fetch.test.ts

@@ -0,0 +1,139 @@
+import { describe, it, expect, vi } from 'vitest'
+import { mkdtempSync, readFileSync, rmSync, existsSync, readdirSync, mkdirSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fetchWebBundle } from './fetch.js'
+import { makeBundleTgz } from './test-helpers.js'
+
+function registryFetch(opts: { tgz: Buffer; integrity: string; version?: string }) {
+  const version = opts.version ?? '0.1.0'
+  return vi.fn(async (url: string | URL) => {
+    const u = String(url)
+    if (u === 'https://registry.npmjs.org/@zooid/zoon-web') {
+      return new Response(
+        JSON.stringify({
+          'dist-tags': { latest: version },
+          versions: {
+            [version]: {
+              dist: {
+                tarball: `https://registry.npmjs.org/@zooid/zoon-web/-/zoon-web-${version}.tgz`,
+                integrity: opts.integrity,
+              },
+            },
+          },
+        }),
+        { status: 200 },
+      )
+    }
+    if (u.endsWith(`/zoon-web-${version}.tgz`)) {
+      return new Response(new Uint8Array(opts.tgz), { status: 200 })
+    }
+    return new Response('not found', { status: 404 })
+  }) as unknown as typeof fetch
+}
+
+describe('fetchWebBundle', () => {
+  let cacheDir: string
+  const setup = () => (cacheDir = mkdtempSync(join(tmpdir(), 'zooid-webcache-')))
+  const teardown = () => rmSync(cacheDir, { recursive: true, force: true })
+
+  it('downloads, verifies, extracts dist/ into <cacheDir>/<version>', async () => {
+    setup()
+    try {
+      const { tgz, integrity } = makeBundleTgz()
+      const f = registryFetch({ tgz, integrity })
+      const root = await fetchWebBundle({ version: '0.1.0', cacheDir, fetch: f })
+      expect(root).toBe(join(cacheDir, '0.1.0'))
+      expect(readFileSync(join(root, 'index.html'), 'utf8')).toBe('<html>zoon</html>')
+      expect(readFileSync(join(root, 'assets', 'app.js'), 'utf8')).toBe('// app')
+    } finally {
+      teardown()
+    }
+  })
+
+  it('returns the cache on a second call without touching the network', async () => {
+    setup()
+    try {
+      const { tgz, integrity } = makeBundleTgz()
+      const f = registryFetch({ tgz, integrity })
+      await fetchWebBundle({ version: '0.1.0', cacheDir, fetch: f })
+      const fCold = vi.fn() as unknown as typeof fetch
+      const root = await fetchWebBundle({ version: '0.1.0', cacheDir, fetch: fCold })
+      expect(root).toBe(join(cacheDir, '0.1.0'))
+      expect(fCold).not.toHaveBeenCalled()
+    } finally {
+      teardown()
+    }
+  })
+
+  it('rejects on integrity mismatch and leaves no version dir behind', async () => {
+    setup()
+    try {
+      const { tgz } = makeBundleTgz()
+      const f = registryFetch({ tgz, integrity: 'sha512-' + 'A'.repeat(88) })
+      await expect(fetchWebBundle({ version: '0.1.0', cacheDir, fetch: f })).rejects.toThrow(
+        /integrity/i,
+      )
+      expect(existsSync(join(cacheDir, '0.1.0'))).toBe(false)
+    } finally {
+      teardown()
+    }
+  })
+
+  it('fails with an actionable error when the pinned version is not on the registry', async () => {
+    setup()
+    try {
+      const { tgz, integrity } = makeBundleTgz()
+      const f = registryFetch({ tgz, integrity, version: '0.0.9' })
+      await expect(fetchWebBundle({ version: '0.1.0', cacheDir, fetch: f })).rejects.toThrow(
+        /@zooid\/zoon-web@0\.1\.0/,
+      )
+    } finally {
+      teardown()
+    }
+  })
+
+  it('names the cache path and the env override when the network is down', async () => {
+    setup()
+    try {
+      const f = vi.fn(async () => {
+        throw new TypeError('fetch failed')
+      }) as unknown as typeof fetch
+      await expect(fetchWebBundle({ version: '0.1.0', cacheDir, fetch: f })).rejects.toThrow(
+        /ZOOID_DEV_WEB_ROOT_OVERRIDE/,
+      )
+    } finally {
+      teardown()
+    }
+  })
+
+  it('prunes other version dirs after a successful fetch', async () => {
+    setup()
+    try {
+      const stale = join(cacheDir, '0.0.9')
+      mkdirSync(stale, { recursive: true })
+      writeFileSync(join(stale, 'index.html'), 'old')
+      const { tgz, integrity } = makeBundleTgz()
+      await fetchWebBundle({ version: '0.1.0', cacheDir, fetch: registryFetch({ tgz, integrity }) })
+      expect(readdirSync(cacheDir).sort()).toEqual(['0.1.0'])
+    } finally {
+      teardown()
+    }
+  })
+
+  it('does not treat a half-extracted dir as a cache hit', async () => {
+    setup()
+    try {
+      // a version dir without the completion marker = crashed mid-extract
+      const partial = join(cacheDir, '0.1.0')
+      mkdirSync(partial, { recursive: true })
+      const { tgz, integrity } = makeBundleTgz()
+      const f = registryFetch({ tgz, integrity })
+      const root = await fetchWebBundle({ version: '0.1.0', cacheDir, fetch: f })
+      expect(readFileSync(join(root, 'index.html'), 'utf8')).toBe('<html>zoon</html>')
+      expect(f).toHaveBeenCalled()
+    } finally {
+      teardown()
+    }
+  })
+})

package/src/web/fetch.ts

@@ -0,0 +1,85 @@
+import { mkdirSync, renameSync, rmSync, existsSync, readdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { createHash, randomUUID } from 'node:crypto'
+import * as tar from 'tar'
+
+const PKG = '@zooid/zoon-web'
+const DEFAULT_REGISTRY = 'https://registry.npmjs.org'
+
+export interface FetchWebBundleOptions {
+  version: string
+  cacheDir: string
+  registryUrl?: string
+  fetch?: typeof globalThis.fetch
+}
+
+/**
+ * Ensure <cacheDir>/<version> holds the extracted dist/ of @zooid/zoon-web.
+ * Atomic: extracts into a temp dir and renames, so a crash never leaves a
+ * half-populated version dir. A populated version dir (index.html present)
+ * is the completion marker.
+ */
+export async function fetchWebBundle(opts: FetchWebBundleOptions): Promise<string> {
+  const target = join(opts.cacheDir, opts.version)
+  if (existsSync(join(target, 'index.html'))) return target
+  if (existsSync(target)) rmSync(target, { recursive: true, force: true }) // crashed extract
+
+  const f = opts.fetch ?? globalThis.fetch
+  const registry = (opts.registryUrl ?? DEFAULT_REGISTRY).replace(/\/$/, '')
+  let tgz: Buffer
+  try {
+    const metaRes = await f(`${registry}/${PKG}`)
+    if (!metaRes.ok) throw new Error(`registry metadata: HTTP ${metaRes.status}`)
+    const meta = (await metaRes.json()) as {
+      versions?: Record<string, { dist?: { tarball?: string; integrity?: string } }>
+    }
+    const dist = meta.versions?.[opts.version]?.dist
+    if (!dist?.tarball || !dist.integrity) {
+      throw new Error(`${PKG}@${opts.version} not found on the registry`)
+    }
+    const tgzRes = await f(dist.tarball)
+    if (!tgzRes.ok) throw new Error(`tarball: HTTP ${tgzRes.status}`)
+    tgz = Buffer.from(await tgzRes.arrayBuffer())
+    const sha = 'sha512-' + createHash('sha512').update(tgz).digest('base64')
+    if (sha !== dist.integrity) {
+      throw new Error(`integrity mismatch for ${PKG}@${opts.version}: got ${sha}`)
+    }
+  } catch (err) {
+    throw new Error(
+      `Failed to fetch ${PKG}@${opts.version} from ${registry}.\n` +
+        `  Cache: ${opts.cacheDir}\n` +
+        `  Offline? Point ZOOID_DEV_WEB_ROOT_OVERRIDE at a built dist as a manual escape hatch.\n` +
+        `  Cause: ${err instanceof Error ? err.message : String(err)}`,
+    )
+  }
+
+  const tmp = join(opts.cacheDir, `.tmp-${randomUUID().slice(0, 8)}`)
+  mkdirSync(tmp, { recursive: true })
+  const tgzPath = join(tmp, '.bundle.tgz')
+  try {
+    writeFileSync(tgzPath, tgz)
+    // node-tar handles gunzip, pax headers, and long names itself, and its
+    // defaults refuse absolute paths and `..` traversal.
+    await tar.extract({
+      file: tgzPath,
+      cwd: tmp,
+      strip: 2, // package/dist/<file> → <file>
+      filter: (p) => p === 'package/dist' || p.startsWith('package/dist/'),
+    })
+    rmSync(tgzPath)
+    if (!existsSync(join(tmp, 'index.html'))) {
+      throw new Error(`${PKG}@${opts.version} tarball has no dist/index.html`)
+    }
+    renameSync(tmp, target)
+  } catch (err) {
+    rmSync(tmp, { recursive: true, force: true })
+    throw err
+  }
+
+  for (const entry of readdirSync(opts.cacheDir)) {
+    if (entry !== opts.version) {
+      rmSync(join(opts.cacheDir, entry), { recursive: true, force: true })
+    }
+  }
+  return target
+}

package/src/web/pin.test.ts

@@ -0,0 +1,24 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { readZoonWebPin } from './pin.js'
+
+let dir: string
+beforeEach(() => (dir = mkdtempSync(join(tmpdir(), 'zooid-pin-'))))
+afterEach(() => rmSync(dir, { recursive: true, force: true }))
+
+describe('readZoonWebPin', () => {
+  it('reads zooid.zoonWebVersion from the cli package.json', () => {
+    writeFileSync(
+      join(dir, 'package.json'),
+      JSON.stringify({ name: 'zooid', zooid: { zoonWebVersion: '0.1.0' } }),
+    )
+    expect(readZoonWebPin(dir)).toBe('0.1.0')
+  })
+
+  it('returns undefined when the field is absent', () => {
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'zooid' }))
+    expect(readZoonWebPin(dir)).toBeUndefined()
+  })
+})

package/src/web/pin.ts

@@ -0,0 +1,13 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export function readZoonWebPin(cliRoot: string): string | undefined {
+  try {
+    const pkg = JSON.parse(readFileSync(join(cliRoot, 'package.json'), 'utf8')) as {
+      zooid?: { zoonWebVersion?: string }
+    }
+    return pkg.zooid?.zoonWebVersion
+  } catch {
+    return undefined
+  }
+}

package/src/web/resolve.test.ts

@@ -1,47 +1,75 @@
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { afterEach, beforeEach, describe, expect, it } from 'vitest'
-import { resolveWebRoot, webSourcePackage } from './resolve.js'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { ensureWebRoot, webSourcePackage } from './resolve.js'
 
 let root: string
 beforeEach(() => {
   root = mkdtempSync(join(tmpdir(), 'zooid-resolve-'))
 })
-afterEach(() => rmSync(root, { recursive: true, force: true }))
-
-describe('resolveWebRoot', () => {
-  it('returns dist/web when present (published-package layout)', () => {
-    const distWeb = join(root, 'dist', 'web')
-    mkdirSync(distWeb, { recursive: true })
-    writeFileSync(join(distWeb, 'index.html'), '<html/>')
-    expect(resolveWebRoot(root)).toBe(distWeb)
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true })
+  delete process.env.ZOOID_DEV_WEB_ROOT_OVERRIDE
+})
+
+function makeSibling(rootDir: string): { cliRoot: string; webDist: string } {
+  const cliRoot = join(rootDir, 'zooid', 'packages', 'cli')
+  mkdirSync(cliRoot, { recursive: true })
+  const webPkg = join(rootDir, 'zoon', 'packages', 'web')
+  const webDist = join(webPkg, 'dist')
+  mkdirSync(webDist, { recursive: true })
+  writeFileSync(join(webPkg, 'package.json'), '{"name":"@zooid/zoon-web"}')
+  writeFileSync(join(webDist, 'index.html'), '<html/>')
+  return { cliRoot, webDist }
+}
+
+describe('ensureWebRoot', () => {
+  it('env override wins over everything and skips the fetch', async () => {
+    const { cliRoot } = makeSibling(root)
+    const override = join(root, 'override')
+    mkdirSync(override, { recursive: true })
+    writeFileSync(join(override, 'index.html'), '<html/>')
+    process.env.ZOOID_DEV_WEB_ROOT_OVERRIDE = override
+    const fetchBundle = vi.fn()
+    const out = await ensureWebRoot({ cliRoot, cacheDir: join(root, 'cache'), version: '0.1.0', fetchBundle })
+    expect(out).toBe(override)
+    expect(fetchBundle).not.toHaveBeenCalled()
   })
 
-  it('falls back to ../../zoon/packages/web/dist when running from source', () => {
-    const cliRoot = join(root, 'zooid', 'packages', 'cli')
+  it('prefers the monorepo sibling dist over the cache (contributor path)', async () => {
+    const { cliRoot, webDist } = makeSibling(root)
+    const fetchBundle = vi.fn()
+    const out = await ensureWebRoot({ cliRoot, cacheDir: join(root, 'cache'), version: '0.1.0', fetchBundle })
+    expect(out).toBe(webDist)
+    expect(fetchBundle).not.toHaveBeenCalled()
+  })
+
+  it('falls back to fetchBundle outside the monorepo (installed-package path)', async () => {
+    const cliRoot = join(root, 'lonely', 'cli')
     mkdirSync(cliRoot, { recursive: true })
-    const webPkg = join(root, 'zoon', 'packages', 'web')
-    const webDist = join(webPkg, 'dist')
-    mkdirSync(webDist, { recursive: true })
-    writeFileSync(join(webPkg, 'package.json'), '{"name":"@zoon/web"}')
-    writeFileSync(join(webDist, 'index.html'), '<html/>')
-    expect(resolveWebRoot(cliRoot)).toBe(webDist)
+    const cached = join(root, 'cache', '0.1.0')
+    const fetchBundle = vi.fn(async () => cached)
+    const out = await ensureWebRoot({ cliRoot, cacheDir: join(root, 'cache'), version: '0.1.0', fetchBundle })
+    expect(out).toBe(cached)
+    expect(fetchBundle).toHaveBeenCalledWith(
+      expect.objectContaining({ version: '0.1.0', cacheDir: join(root, 'cache') }),
+    )
   })
 
-  it('throws a helpful error when neither layout has been built', () => {
-    expect(() => resolveWebRoot(root)).toThrow(/@zoon\/web.*build/i)
+  it('throws an actionable error when no version pin is available outside the monorepo', async () => {
+    const cliRoot = join(root, 'lonely', 'cli')
+    mkdirSync(cliRoot, { recursive: true })
+    await expect(
+      ensureWebRoot({ cliRoot, cacheDir: join(root, 'cache'), version: undefined, fetchBundle: vi.fn() }),
+    ).rejects.toThrow(/zoonWebVersion/)
   })
 })
 
 describe('webSourcePackage', () => {
   it('returns the source package dir when sibling zoon/packages/web exists', () => {
-    const cliRoot = join(root, 'zooid', 'packages', 'cli')
-    mkdirSync(cliRoot, { recursive: true })
-    const webPkg = join(root, 'zoon', 'packages', 'web')
-    mkdirSync(webPkg, { recursive: true })
-    writeFileSync(join(webPkg, 'package.json'), '{"name":"@zoon/web"}')
-    expect(webSourcePackage(cliRoot)).toBe(webPkg)
+    const { cliRoot } = makeSibling(root)
+    expect(webSourcePackage(cliRoot)).toBe(join(root, 'zoon', 'packages', 'web'))
   })
 
   it('returns null outside the monorepo', () => {