zooid 0.12.0 → 0.14.0

package/dist/index.d.ts

@@ -16,13 +16,13 @@ interface BuildAcpRegistryOptions {
     agentsDir?: string;
     /**
      * Per-spawn binding store for the zooid-context MCP server. When set
-     * together with `daemonSockPath`, agents bound to a transport that owns
+     * together with `daemonSockPaths`, agents bound to a transport that owns
      * conversation context get a `contextSpawn` factory threaded into their
      * AcpClient so `session/new mcpServers` includes the zooid-context entry.
      */
     contextSpawnRegistry?: SpawnRegistry;
-    /** Path to the daemon's context Unix socket. Passed to the MCP server bin. */
-    daemonSockPath?: string;
+    /** Agent → host path to that agent's context Unix socket. */
+    daemonSockPaths?: Record<string, string | undefined>;
     /**
      * Directory containing zooid.yaml. Required when any agent uses the
      * workspace auto-mount (the default under `runtime: docker | podman`):

package/dist/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zooid",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "An open-source, self-hostable chat app for collaborating with AI agents alongside your team. Any model, any CLI.",
   "type": "module",
   "license": "MIT",
@@ -25,7 +25,7 @@
     "access": "public"
   },
   "zooid": {
-    "webVersion": "0.10.0"
+    "webVersion": "0.12.0"
   },
   "engines": {
     "node": ">=22"
@@ -35,24 +35,28 @@
     "@inquirer/prompts": "^8.4.3",
     "cac": "^6.7.14",
     "chalk": "^5.4.1",
+    "croner": "^10.0.1",
     "hono": "^4.6.0",
     "listr2": "^8.2.5",
     "marked": "^18.0.4",
     "sanitize-html": "^2.17.4",
     "tar": "^7.5.16",
+    "web-push": "^3.6.7",
     "yaml": "^2.5.0",
-    "@zooid/context-mcp": "^0.12.0",
-    "@zooid/acp-client": "^0.12.0",
-    "@zooid/core": "^0.12.0",
-    "@zooid/runtime-docker": "^0.12.0",
-    "@zooid/transport-http": "^0.12.0",
-    "@zooid/runtime-local": "^0.12.0",
-    "@zooid/transport-matrix": "^0.12.0"
+    "@zooid/acp-client": "^0.14.0",
+    "@zooid/core": "^0.14.0",
+    "@zooid/pi-extension": "^0.13.1",
+    "@zooid/runtime-docker": "^0.14.0",
+    "@zooid/context-mcp": "^0.14.0",
+    "@zooid/runtime-local": "^0.14.0",
+    "@zooid/transport-matrix": "^0.14.0",
+    "@zooid/transport-http": "^0.14.0"
   },
   "devDependencies": {
     "@agentclientprotocol/sdk": "^0.21.0",
     "@playwright/test": "^1.49.0",
     "@types/node": "^22.0.0",
+    "@types/web-push": "^3.6.4",
     "release-it": "^19.2.4",
     "tsup": "^8.5.1",
     "tsx": "^4.19.0",

package/src/bin.test.ts

@@ -0,0 +1,63 @@
+import { spawnSync } from 'node:child_process'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const TSX = join(HERE, '..', 'node_modules', '.bin', 'tsx')
+const BIN = join(HERE, 'bin.ts')
+
+function runCli(args: string[]) {
+  const result = spawnSync(TSX, [BIN, ...args], { encoding: 'utf8' })
+  return { stdout: result.stdout, stderr: result.stderr, status: result.status }
+}
+
+describe('zooid help', () => {
+  it('lists every registered command with no args', () => {
+    const { stdout, status } = runCli([])
+    expect(status).toBe(1)
+    for (const name of ['start', 'dev', 'logs', 'status', 'init', 'help']) {
+      expect(stdout).toContain(name)
+    }
+  })
+
+  it('--help prints the same command list and exits 0', () => {
+    const { stdout, status } = runCli(['--help'])
+    expect(status).toBe(0)
+    expect(stdout).toContain('Commands:')
+    expect(stdout).toContain('init [dir]')
+  })
+
+  it('`zooid help` mirrors `zooid --help`', () => {
+    const { stdout, status } = runCli(['help'])
+    expect(status).toBe(0)
+    expect(stdout).toContain('Commands:')
+  })
+
+  it('`zooid help <command>` shows that command\'s own help', () => {
+    const { stdout, status } = runCli(['help', 'init'])
+    expect(status).toBe(0)
+    expect(stdout).toContain('$ zooid init [dir]')
+    expect(stdout).toContain('--preset <name>')
+  })
+
+  it('`zooid <command> --help` still works directly', () => {
+    const { stdout, status } = runCli(['logs', '--help'])
+    expect(status).toBe(0)
+    expect(stdout).toContain('$ zooid logs [source]')
+  })
+
+  it('rejects an unknown subcommand of help', () => {
+    const { stdout, stderr, status } = runCli(['help', 'bogus'])
+    expect(status).toBe(1)
+    expect(stderr).toContain('Unknown command: bogus')
+    expect(stdout).toContain('Commands:')
+  })
+
+  it('rejects an unknown top-level command instead of exiting silently', () => {
+    const { stdout, stderr, status } = runCli(['frobnicate'])
+    expect(status).toBe(1)
+    expect(stderr).toContain('Unknown command: frobnicate')
+    expect(stdout).toContain('Commands:')
+  })
+})

package/src/bin.ts

@@ -6,6 +6,7 @@ import { resolveOptions } from './commands/init/prompts.js'
 import { runLogs } from './commands/logs.js'
 import { runStart } from './commands/start.js'
 import { runStatus } from './commands/status.js'
+import { CLI_VERSION } from './version.js'
 
 const cli = cac('zooid')
 
@@ -15,6 +16,8 @@ cli
   .option('--runtime <local|docker|podman>', 'Agent runtime')
   .option('--image <ref>', 'Agent container image')
   .option('--print-token', 'Print a 32-byte hex token and exit')
+  .example('$ zooid start --data ./data')
+  .example('$ zooid start --runtime docker --image ghcr.io/zooid-ai/agent:latest')
   .action(async (flags) => {
     await runStart({
       dataDir: flags.data,
@@ -35,6 +38,8 @@ cli
     '--watch-web [path]',
     'Run vite build --watch on @zooid/web. Path defaults to sibling ../zooid-clients/packages/web.',
   )
+  .example('$ zooid dev')
+  .example('$ zooid dev --engine podman --ui-port 5174')
   .action(async (flags) => {
     await runDev({
       dataDir: flags.data,
@@ -56,6 +61,9 @@ cli
   .option('--turn <id>', 'Filter ACP taps to a single turn id')
   .option('-f, --follow', 'Tail the file (not yet implemented)')
   .option('--keep <n>', 'For `logs prune`: days to retain', { default: 14 })
+  .example('$ zooid logs daemon')
+  .example('$ zooid logs agent-support.acp --turn 3f9c1a --day 2026-09-06')
+  .example('$ zooid logs prune --keep 7')
   .action(async (source, flags) => {
     if (source === 'prune') {
       await runLogs({
@@ -78,6 +86,7 @@ cli
   .command('status', 'Print Tuwunel + daemon health')
   .option('--data <dir>', 'Persistent data root dir', { default: './data' })
   .option('--port <n>', 'Tuwunel host port (defaults to zooid.yaml)')
+  .example('$ zooid status')
   .action(async (flags) => {
     await runStatus({
       dataDir: flags.data,
@@ -95,6 +104,9 @@ cli
   .option('--force', 'Allow scaffolding into a non-empty directory')
   .option('--overwrite', 'With --force, overwrite existing files')
   .option('--no-interactive', 'Disable prompts; require all flags up front')
+  .example('$ zooid init')
+  .example('$ zooid init my-workforce --preset opencode --provider anthropic')
+  .example('$ zooid init --preset claude --auth api-key --api-key sk-... --no-interactive')
   .action(async (dir: string | undefined, flags) => {
     const resolved = await resolveOptions({
       dir: dir ?? process.cwd(),
@@ -110,6 +122,43 @@ cli
     await runInit(resolved)
   })
 
-cli.help()
-cli.version('0.0.1')
-cli.parse()
+cli
+  .command('help [command]', 'Display help for zooid, or for a specific command')
+  .example('$ zooid help')
+  .example('$ zooid help init')
+  .action((commandName?: string) => {
+    if (!commandName) {
+      cli.globalCommand.outputHelp()
+      return
+    }
+    const target = cli.commands.find((c) => c.isMatched(commandName))
+    if (!target) {
+      console.error(`Unknown command: ${commandName}\n`)
+      cli.globalCommand.outputHelp()
+      process.exitCode = 1
+      return
+    }
+    target.outputHelp()
+  })
+
+cli.help((sections) => {
+  sections.push({
+    title: 'Docs',
+    body: '  https://zooid.dev/docs',
+  })
+  return sections
+})
+cli.version(CLI_VERSION)
+
+cli.on('command:*', () => {
+  console.error(`Unknown command: ${cli.args.join(' ')}\n`)
+  cli.outputHelp()
+  process.exitCode = 1
+})
+
+if (process.argv.slice(2).length === 0) {
+  cli.outputHelp()
+  process.exitCode = 1
+} else {
+  cli.parse()
+}

package/src/bootstrap/configs.test.ts

@@ -15,6 +15,13 @@ describe('renderTuwunelToml', () => {
     )
     expect(toml).toContain('allow_local_presence = true')
     expect(toml).toContain('port = [8448]')
+    // Presence-based push suppression stays OFF — sw.js suppresses per-room
+    // on visibility instead, and presence lingers long past a closed tab.
+    expect(toml).not.toContain('suppress_push_when_active')
+    // DEV ONLY: Tuwunel is in Podman, the push gateway runs on the host, and
+    // the default ip_range_denylist (127/8, 10/8, 172.16/12, 192.168/16, ::1)
+    // would silently drop every pusher delivery to it.
+    expect(toml).toContain('ip_range_denylist = []')
   })
 
   it('honors a non-default server_name', () => {

package/src/bootstrap/configs.ts

@@ -26,6 +26,20 @@ export function renderTuwunelToml(opts: TuwunelTomlOpts): string {
     'allow_local_presence = true',
     'address = ["0.0.0.0"]',
     `port = [${TUWUNEL_INTERNAL_PORT}]`,
+    // NOT `suppress_push_when_active` ([[ZNC025]]). It reads Matrix presence,
+    // which is both too coarse and too slow for this: coarse because it is
+    // per-user, so reading room A kills the push for room B; slow because
+    // `currently_active` lingers for minutes after the last sync, so closing
+    // the tab and waiting for an agent to finish still delivers nothing —
+    // exactly the case this feature exists for. `public/sw.js` already does
+    // the suppression we actually want, precisely: it drops a push only when
+    // a *visible* window is on *that* room.
+    // DEV ONLY — disables an SSRF guard. Tuwunel is in Podman and the push
+    // gateway runs on the host, so the default ip_range_denylist (127/8,
+    // 10/8, 172.16/12, 192.168/16, ::1) silently drops every pusher delivery.
+    // Never set on a box: there the gateway is reached at the public
+    // hostname through Caddy.
+    'ip_range_denylist = []',
     '',
   ].join('\n')
 }

package/src/build-registry.context.test.ts

@@ -44,7 +44,7 @@ describe('buildAcpRegistry — context provider wiring', () => {
     const registry = buildAcpRegistry(matrixCfg, {
       approvals: { register: vi.fn(), on: vi.fn() } as never,
       contextSpawnRegistry: {} as never,
-      daemonSockPath: '/tmp/zooid-test.sock',
+      daemonSockPaths: { architect: '/tmp/zooid-test.sock' },
     })
     expect(registry.hasContextSpawn('architect')).toBe(true)
   })
@@ -59,7 +59,7 @@ describe('buildAcpRegistry — context provider wiring', () => {
     const registry = buildAcpRegistry(httpCfg, {
       approvals: { register: vi.fn(), on: vi.fn() } as never,
       contextSpawnRegistry: {} as never,
-      daemonSockPath: '/tmp/zooid-test.sock',
+      daemonSockPaths: { architect: '/tmp/zooid-test.sock' },
     })
     expect(registry.hasContextSpawn('architect')).toBe(false)
   })
@@ -77,7 +77,7 @@ describe('buildAcpRegistry — context provider in a container runtime', () => {
   const opts = {
     approvals: { register: vi.fn(), on: vi.fn() } as never,
     contextSpawnRegistry: { register: vi.fn(() => 'spawn-1') } as never,
-    daemonSockPath: '/home/ubuntu/hq/data/run/context.sock',
+    daemonSockPaths: { architect: '/home/ubuntu/hq/data/run/context.sock' },
     daemonHome: '/home/ubuntu',
   }
 

package/src/build-registry.ts

@@ -14,7 +14,12 @@ import {
   type TransportContextProvider,
 } from '@zooid/core'
 import { MatrixClient, MatrixContextProvider } from '@zooid/transport-matrix'
-import { SpawnRegistry, buildContextServerSpec, contextContainerMounts } from '@zooid/context-mcp'
+import {
+  CONTEXT_CONTAINER_SOCK,
+  SpawnRegistry,
+  buildContextServerSpec,
+  contextContainerMounts,
+} from '@zooid/context-mcp'
 import { PRESETS, type PresetMount, type PresetName } from '@zooid/acp-client'
 
 export interface BuildAcpRegistryOptions {
@@ -32,13 +37,13 @@ export interface BuildAcpRegistryOptions {
   agentsDir?: string
   /**
    * Per-spawn binding store for the zooid-context MCP server. When set
-   * together with `daemonSockPath`, agents bound to a transport that owns
+   * together with `daemonSockPaths`, agents bound to a transport that owns
    * conversation context get a `contextSpawn` factory threaded into their
    * AcpClient so `session/new mcpServers` includes the zooid-context entry.
    */
   contextSpawnRegistry?: SpawnRegistry
-  /** Path to the daemon's context Unix socket. Passed to the MCP server bin. */
-  daemonSockPath?: string
+  /** Agent → host path to that agent's context Unix socket. */
+  daemonSockPaths?: Record<string, string | undefined>
   /**
    * Directory containing zooid.yaml. Required when any agent uses the
    * workspace auto-mount (the default under `runtime: docker | podman`):
@@ -78,10 +83,7 @@ function presetOf(agent: AgentConfig): PresetName | undefined {
   return undefined
 }
 
-function resolveAgentImage(
-  agent: AgentConfig,
-  cfg: ZooidConfig,
-): ResolvedImage {
+function resolveAgentImage(agent: AgentConfig, cfg: ZooidConfig): ResolvedImage {
   if (agent.container?.image) return { image: agent.container.image, source: 'agent' }
   if (cfg.container?.image) return { image: cfg.container.image, source: 'workforce' }
   const preset = presetOf(agent)
@@ -183,9 +185,7 @@ function composeAgentMounts(
     composed.push(out)
   }
 
-  const mkdirs: string[] = composed
-    .filter((m) => m.create)
-    .map((m) => m.host)
+  const mkdirs: string[] = composed.filter((m) => m.create).map((m) => m.host)
 
   return {
     mounts: composed,
@@ -227,8 +227,9 @@ export function buildAcpRegistry(
       }
     }
     if (missing.length > 0) {
-      const lines = missing.map(({ name, preset }) =>
-        `  - ${name}${preset ? ` (preset: ${preset})` : ''} — no preset-default image`,
+      const lines = missing.map(
+        ({ name, preset }) =>
+          `  - ${name}${preset ? ` (preset: ${preset})` : ''} — no preset-default image`,
       )
       throw new Error(
         `runtime: ${cfg.runtime} requires a container image for each agent. Unresolved:\n` +
@@ -260,9 +261,10 @@ export function buildAcpRegistry(
     mkdirByAgent[name] = composed.mkdirs
     cwdByAgent[name] = composed.cwd
     if (resolvedImage && cfg.runtime !== 'local') {
-      const mountSummary = composed.mounts.length === 0
-        ? 'mounts=[]'
-        : `mounts=[${composed.mounts.map((m) => m.id ?? m.target).join(',')}]`
+      const mountSummary =
+        composed.mounts.length === 0
+          ? 'mounts=[]'
+          : `mounts=[${composed.mounts.map((m) => m.id ?? m.target).join(',')}]`
       log(
         `[zooid] agent ${name.padEnd(12)} image=${resolvedImage}  source=${source}  ${mountSummary}`,
       )
@@ -271,16 +273,33 @@ export function buildAcpRegistry(
 
   const contextSpawns = buildContextSpawns(cfg, opts)
 
+  // Extensions run in the agent process (rather than an MCP child), so all
+  // context-enabled agents inherit the daemon socket address directly.
+  if (contextSpawns) {
+    for (const name of Object.keys(cfg.agents)) {
+      if (!contextSpawns[name]) continue
+      const agentSock = opts.daemonSockPaths?.[name]
+      if (!agentSock) continue
+      env[name] = {
+        ZOOID_DAEMON_SOCK:
+          cfg.runtime === 'local' ? agentSock : CONTEXT_CONTAINER_SOCK,
+        ...env[name],
+      }
+    }
+  }
+
   // Container runtimes: opencode spawns the zooid-context MCP subprocess INSIDE
   // its container, so the daemon socket + the (self-contained) bin must be
   // bind-mounted in. Local runtime needs neither — the host spec resolves
   // directly. Only agents that actually got a context factory get the mounts.
-  if (cfg.runtime !== 'local' && opts.daemonSockPath && contextSpawns) {
+  if (cfg.runtime !== 'local' && contextSpawns) {
     for (const name of Object.keys(cfg.agents)) {
       if (!contextSpawns[name]) continue
+      const agentSock = opts.daemonSockPaths?.[name]
+      if (!agentSock) continue
       mountsByAgent[name] = [
         ...(mountsByAgent[name] ?? []),
-        ...contextContainerMounts({ sockPath: opts.daemonSockPath }),
+        ...contextContainerMounts({ sockPath: agentSock }),
       ]
     }
   }
@@ -297,6 +316,8 @@ export function buildAcpRegistry(
     onTap: opts.onTap,
     agentsDir: opts.agentsDir,
     contextSpawns,
+    onSessionEstablished: (agentName, sessionKey, sessionId) =>
+      opts.contextSpawnRegistry?.linkSession(agentName, sessionKey, sessionId),
   })
 }
 
@@ -304,9 +325,8 @@ function buildContextSpawns(
   cfg: ZooidConfig,
   opts: BuildAcpRegistryOptions,
 ): Record<string, ContextSpawnFactory | undefined> | undefined {
-  if (!opts.contextSpawnRegistry || !opts.daemonSockPath) return undefined
+  if (!opts.contextSpawnRegistry || !opts.daemonSockPaths) return undefined
   const registry = opts.contextSpawnRegistry
-  const sockPath = opts.daemonSockPath
 
   const matrixClients = new Map<string, MatrixClient>()
   const agentBots = new Map<string, string>()
@@ -323,18 +343,23 @@ function buildContextSpawns(
 
   const result: Record<string, ContextSpawnFactory | undefined> = {}
   for (const [name, agent] of Object.entries(cfg.agents)) {
-    if (agent.matrix && matrixClients.has(agent.matrix.transport)) {
+    const sockPath = opts.daemonSockPaths[name]
+    if (agent.matrix && matrixClients.has(agent.matrix.transport) && sockPath) {
       const client = matrixClients.get(agent.matrix.transport)!
       const provider: TransportContextProvider = new MatrixContextProvider({
         client,
         asUserId: agent.matrix.user_id,
         agentBots,
+        // Same array BotPool.bootstrap rewrites `.alias` on in place — reads
+        // through this after bootstrap see canonical room IDs.
+        rooms: agent.matrix.rooms,
       })
-      result[name] = async (threadId: string, channelId?: string) => {
+      result[name] = async (threadId: string, channelId?: string, sessionKey?: string) => {
         const spawnId = registry.register({
           agentName: name,
           threadRef: { channelId: channelId ?? threadId, threadId },
           provider,
+          sessionKey: sessionKey ?? threadId,
         })
         return buildContextServerSpec({
           spawnId,
@@ -349,13 +374,31 @@ function buildContextSpawns(
   return result
 }
 
+/** Agents on configured Matrix transports get a context listener and binding. */
+export function contextEligibleAgents(cfg: ZooidConfig): string[] {
+  const matrixTransports = new Set(
+    Object.entries(cfg.transports)
+      .filter(([, transport]) => transport.type === 'matrix')
+      .map(([name]) => name),
+  )
+  return Object.entries(cfg.agents)
+    .filter(([, agent]) => agent.matrix && matrixTransports.has(agent.matrix.transport))
+    .map(([name]) => name)
+}
+
 function defaultRuntimeFor(cfg: ZooidConfig): AcpRuntime {
   if (cfg.runtime === 'local') return new LocalAcpRuntime()
   if (cfg.runtime === 'docker') {
-    return new DockerAcpRuntime({ defaultImage: cfg.container?.image, engine: 'docker' })
+    return new DockerAcpRuntime({
+      defaultImage: cfg.container?.image,
+      engine: 'docker',
+    })
   }
   if (cfg.runtime === 'podman') {
-    return new DockerAcpRuntime({ defaultImage: cfg.container?.image, engine: 'podman' })
+    return new DockerAcpRuntime({
+      defaultImage: cfg.container?.image,
+      engine: 'podman',
+    })
   }
   throw new Error(`unsupported runtime: ${cfg.runtime}`)
 }

package/src/commands/dev.ts

@@ -248,7 +248,22 @@ export async function runDev(flags: DevFlags): Promise<DevHandle> {
                 t.output = msg
               },
             }))
-          const app = webStatic({ webRoot, homeserverUrl: homeserver })
+          const app = webStatic({
+            webRoot,
+            homeserverUrl: homeserver,
+            ...(ctx.daemon?.vapidPublicKey
+              ? {
+                  // Tuwunel runs in a container; `localhost` here would
+                  // resolve to the container, not the daemon. Same shorthand
+                  // as the AS registration url
+                  // (bootstrap/registration-url.ts). This URL is stored in
+                  // the pusher and fetched by the homeserver — the browser
+                  // never requests it.
+                  pushGatewayUrl: `http://host.docker.internal:${ctx.daemon.port}/_matrix/push/v1/notify`,
+                  vapidPublicKey: ctx.daemon.vapidPublicKey,
+                }
+              : {}),
+          })
           ctx.uiServer = serve({ fetch: app.fetch, port: flags.uiPort })
         },
       },
@@ -287,13 +302,28 @@ export async function runDev(flags: DevFlags): Promise<DevHandle> {
   })
 
   if (flags.installSignalHandlers !== false) {
-    const handler = async (): Promise<void> => {
-      process.stdout.write(chalk.dim('\nStopping…\n'))
-      await shutdown()
-      process.exit(0)
+    // buildShutdown is idempotent, so a repeat Ctrl-C used to print again and
+    // await the same promise, with no way to give up on a step taking too
+    // long. Escalate on repeats instead.
+    let interrupts = 0
+    const onSignal = (): void => {
+      interrupts += 1
+      if (interrupts === 1) {
+        process.stdout.write(chalk.dim('\nStopping…\n'))
+        void shutdown().then(() => process.exit(0))
+        return
+      }
+      if (interrupts === 2) {
+        process.stdout.write(
+          chalk.dim('Still stopping — press Ctrl-C again to force quit.\n'),
+        )
+        return
+      }
+      process.stdout.write(chalk.dim('Forced.\n'))
+      process.exit(130)
     }
-    process.on('SIGINT', () => void handler())
-    process.on('SIGTERM', () => void handler())
+    process.on('SIGINT', onSignal)
+    process.on('SIGTERM', onSignal)
   }
 
   process.stdout.write(

package/src/commands/status.test.ts

@@ -54,6 +54,21 @@ describe('collectStatus', () => {
     ])
   })
 
+  it('reports the VAPID public key when vapid.json exists in the data dir', async () => {
+    writeFileSync(join(dir, 'zooid.yaml'), yaml)
+    writeFileSync(join(dir, 'vapid.json'), JSON.stringify({ publicKey: 'BPk', privateKey: 'priv' }))
+    vi.stubGlobal('fetch', vi.fn(async () => new Response('not found', { status: 404 })))
+    const s = await collectStatus({ cwd: dir, tuwunelUrl: 'http://localhost:8448', dataDir: dir })
+    expect(s.vapidPublicKey).toBe('BPk')
+  })
+
+  it('omits the VAPID key when no daemon has run yet', async () => {
+    writeFileSync(join(dir, 'zooid.yaml'), yaml)
+    vi.stubGlobal('fetch', vi.fn(async () => new Response('not found', { status: 404 })))
+    const s = await collectStatus({ cwd: dir, tuwunelUrl: 'http://localhost:8448', dataDir: dir })
+    expect(s.vapidPublicKey).toBeUndefined()
+  })
+
   it('reports daemon down when the AS callback port refuses the connection', async () => {
     writeFileSync(join(dir, 'zooid.yaml'), yaml)
     vi.stubGlobal(

package/src/commands/status.ts

@@ -1,8 +1,9 @@
 import { readFileSync } from 'node:fs'
-import { dirname } from 'node:path'
+import { dirname, join, resolve } from 'node:path'
 import chalk from 'chalk'
 import { findConfigFile, findMatrixTransport, loadZooidConfig } from '@zooid/core'
 import { deriveHomeserverShape } from '../bootstrap/derive.js'
+import { VAPID_FILENAME } from '../push-gateway/vapid.js'
 
 export interface StatusFlags {
   cwd?: string
@@ -15,6 +16,24 @@ export interface StatusReport {
   tuwunel: { status: 'up' | 'down'; url: string }
   daemon: { status: 'up' | 'down'; url: string } | { status: 'unknown'; reason: string }
   agents: { name: string; userId: string; trigger: string }[]
+  /** VAPID public key read from `<dataDir>/vapid.json`, when it exists. */
+  vapidPublicKey?: string
+}
+
+/**
+ * Read the daemon's VAPID public key straight off disk. Operators
+ * hand-editing a box's config.json need it and can't start a daemon just to
+ * ask, so this reads the persisted file rather than starting one.
+ */
+export function readVapidPublicKey(dataDir: string): string | undefined {
+  try {
+    const parsed = JSON.parse(readFileSync(join(dataDir, VAPID_FILENAME), 'utf8')) as {
+      publicKey?: string
+    }
+    return typeof parsed.publicKey === 'string' ? parsed.publicKey : undefined
+  } catch {
+    return undefined
+  }
 }
 
 async function probe(url: string, timeoutMs = 2_000): Promise<boolean> {
@@ -29,12 +48,14 @@ async function probe(url: string, timeoutMs = 2_000): Promise<boolean> {
 export async function collectStatus(opts: {
   cwd: string
   tuwunelUrl: string
+  dataDir?: string
 }): Promise<StatusReport> {
   const tuwunelUp = await probe(`${opts.tuwunelUrl}/_matrix/client/versions`)
   const tuwunel: StatusReport['tuwunel'] = {
     status: tuwunelUp ? 'up' : 'down',
     url: opts.tuwunelUrl,
   }
+  const vapidPublicKey = opts.dataDir ? readVapidPublicKey(opts.dataDir) : undefined
 
   const found = findConfigFile(opts.cwd)
   if (!found) {
@@ -42,6 +63,7 @@ export async function collectStatus(opts: {
       tuwunel,
       daemon: { status: 'unknown', reason: 'no zooid.yaml' },
       agents: [],
+      ...(vapidPublicKey ? { vapidPublicKey } : {}),
     }
   }
   const cfg = loadZooidConfig(readFileSync(found.path, 'utf8'), {
@@ -67,6 +89,7 @@ export async function collectStatus(opts: {
     tuwunel,
     daemon: { status: daemonUp ? 'up' : 'down', url: daemonUrl },
     agents,
+    ...(vapidPublicKey ? { vapidPublicKey } : {}),
   }
 }
 
@@ -89,7 +112,8 @@ export async function runStatus(flags: StatusFlags): Promise<void> {
     }
   }
   const tuwunelUrl = `http://localhost:${port ?? 8448}`
-  const s = await collectStatus({ cwd, tuwunelUrl })
+  const dataDir = resolve(cwd, flags.dataDir ?? './data')
+  const s = await collectStatus({ cwd, tuwunelUrl, dataDir })
   const fmt = (st: 'up' | 'down' | 'unknown'): string =>
     st === 'up' ? chalk.green('up') : st === 'down' ? chalk.red('down') : chalk.yellow('unknown')
   process.stdout.write(
@@ -99,6 +123,7 @@ export async function runStatus(flags: StatusFlags): Promise<void> {
       ...s.agents.map(
         (a) => `  agent: ${a.name} (${a.userId}, trigger: ${a.trigger})`,
       ),
+      ...(s.vapidPublicKey ? [`vapid public key: ${s.vapidPublicKey}`] : []),
       '',
     ].join('\n'),
   )