typeclaw 0.36.7 → 0.37.0

package/src/inspect/session-list.ts

@@ -2,6 +2,7 @@ import { readdir, stat } from 'node:fs/promises'
 import { join } from 'node:path'
 
 import type { MinimalSessionOrigin } from '@/agent/session-meta'
+import type { LiveSessionPayload } from '@/shared'
 
 import { previewForHint } from './preview'
 import { replayJsonl } from './replay'
@@ -13,6 +14,11 @@ export type SessionSummary = {
   mtimeMs: number
   origin: MinimalSessionOrigin | null
   firstPrompt: string | null
+  // True only for a registry-derived session with no .jsonl on disk yet (a
+  // reply is in flight). Disk sessions leave this undefined. Selecting one tails
+  // live-only: streamSessionEvents replays an empty file, then the WS delivers
+  // events as they happen.
+  live?: boolean
 }
 
 export type ListSessionsOptions = {
@@ -65,6 +71,29 @@ export async function listSessions(opts: ListSessionsOptions): Promise<SessionSu
   )
 }
 
+// Overlay container-registry sessions onto the disk listing. A live session
+// already flushed to disk (post-reply) is dropped from the overlay — the disk
+// summary wins, carrying its real mtime and prompt preview. Only sessions with
+// no .jsonl yet become synthetic live rows, sorted to the top by registration
+// time so an in-flight reply surfaces above settled history.
+export function mergeLiveSessions(disk: SessionSummary[], live: LiveSessionPayload[]): SessionSummary[] {
+  const onDisk = new Set(disk.map((s) => s.sessionId))
+  const liveOnly = live
+    .filter((l) => !onDisk.has(l.sessionId))
+    .map(
+      (l): SessionSummary => ({
+        sessionId: l.sessionId,
+        sessionFile: '',
+        basename: '',
+        mtimeMs: l.registeredAtMs,
+        origin: l.origin,
+        firstPrompt: null,
+        live: true,
+      }),
+    )
+  return [...liveOnly, ...disk].sort((a, b) => b.mtimeMs - a.mtimeMs)
+}
+
 export type ResolveResult =
   | { ok: true; summary: SessionSummary }
   | { ok: false; reason: 'not-found' | 'ambiguous'; matches: SessionSummary[] }

package/src/models/embedding-model.ts

@@ -0,0 +1,114 @@
+import { readFile, rename, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+export const EMBEDDING_MODEL_NAME = 'Xenova/multilingual-e5-base'
+export const EMBEDDING_MODEL_DTYPE = 'q8'
+export const EMBEDDING_DIMS = 768
+
+// The embedding recipe that makes two vectors comparable: E5 query/passage
+// prefixing + mean pooling + L2 normalize. Stamped in the sentinel (not folded
+// into EMBEDDING_MODEL_ID, which is a stored-row filter — changing the ID would
+// invalidate every existing vector row). A future pooling/normalize change
+// bumps this string so a stale cache fails the sentinel loudly.
+export const EMBEDDING_RECIPE = 'e5-prefix:mean-pool:l2-normalize'
+
+// Stored-row identity = name@dtype. Used by the vector store to filter rows
+// from an incompatible model/dtype variant out of cosine scans.
+export const EMBEDDING_MODEL_ID = `${EMBEDDING_MODEL_NAME}@${EMBEDDING_MODEL_DTYPE}`
+
+const SENTINEL_FILE = '.typeclaw-model.json'
+
+export type ModelSentinel = {
+  schemaVersion: 1
+  model: string
+  dtype: string
+  dims: number
+  recipe: string
+  transformers: string
+}
+
+function sentinelPath(dir: string): string {
+  return join(dir, SENTINEL_FILE)
+}
+
+function expectedSentinel(transformers: string): Omit<ModelSentinel, 'transformers'> & { transformers: string } {
+  return {
+    schemaVersion: 1,
+    model: EMBEDDING_MODEL_NAME,
+    dtype: EMBEDDING_MODEL_DTYPE,
+    dims: EMBEDDING_DIMS,
+    recipe: EMBEDDING_RECIPE,
+    transformers,
+  }
+}
+
+// Atomic write-then-rename so a container reader can never observe a partial
+// JSON file mid-write. Called host-side after a successful model download,
+// inside the proper-lockfile critical section.
+export async function writeModelSentinel(dir: string, input: { transformers: string }): Promise<void> {
+  const sentinel = expectedSentinel(input.transformers)
+  const tmp = `${sentinelPath(dir)}.${process.pid}.tmp`
+  await writeFile(tmp, `${JSON.stringify(sentinel, null, 2)}\n`, 'utf8')
+  await rename(tmp, sentinelPath(dir))
+}
+
+export async function readModelSentinel(dir: string): Promise<ModelSentinel | null> {
+  let raw: string
+  try {
+    raw = await readFile(sentinelPath(dir), 'utf8')
+  } catch {
+    return null
+  }
+  try {
+    const parsed = JSON.parse(raw) as Partial<ModelSentinel>
+    if (
+      parsed.schemaVersion !== 1 ||
+      typeof parsed.model !== 'string' ||
+      typeof parsed.dtype !== 'string' ||
+      typeof parsed.dims !== 'number' ||
+      typeof parsed.recipe !== 'string' ||
+      typeof parsed.transformers !== 'string'
+    ) {
+      return null
+    }
+    return parsed as ModelSentinel
+  } catch {
+    return null
+  }
+}
+
+// Throws a TypeClaw-authored error (naming observed vs expected identity, with
+// the fix) BEFORE the container's `local_files_only` pipeline load — so a
+// host/container drift surfaces as a clear "refresh the cache" message instead
+// of a cryptic missing-file miss, OR worse, a stale file that loads against a
+// different producer's layout and silently returns garbage vectors. Absent
+// sentinel is a hard failure: host ensureModels() writes it before `docker
+// run` in the same `typeclaw start`, so a missing one means the mount is wrong
+// or the cache was hand-copied — exactly the case we must not paper over.
+export async function assertModelCacheCompatible(dir: string, expected: { transformers: string }): Promise<void> {
+  const sentinel = await readModelSentinel(dir)
+  const want = expectedSentinel(expected.transformers)
+  if (sentinel === null) {
+    throw new Error(
+      `TypeClaw model cache at ${dir} is missing or has an unreadable ${SENTINEL_FILE}, so compatibility with ` +
+        `this container cannot be verified. Re-run \`typeclaw start\` to refresh the model cache; if it was copied ` +
+        `manually, delete it and start again.`,
+    )
+  }
+  const mismatches = describeMismatches(sentinel, want)
+  if (mismatches.length > 0) {
+    throw new Error(
+      `TypeClaw model cache at ${dir} is incompatible with this container (${mismatches.join('; ')}). ` +
+        `Re-run \`typeclaw start\` to refresh the model cache.`,
+    )
+  }
+}
+
+function describeMismatches(got: ModelSentinel, want: ModelSentinel): string[] {
+  const fields: Array<keyof ModelSentinel> = ['model', 'dtype', 'dims', 'recipe', 'transformers']
+  return fields
+    .filter((field) => got[field] !== want[field])
+    .map(
+      (field) => `${field}: cache has ${JSON.stringify(got[field])}, container expects ${JSON.stringify(want[field])}`,
+    )
+}

package/src/models/transformers-version.ts

@@ -0,0 +1,55 @@
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join, parse as parsePath } from 'node:path'
+
+// The ACTUALLY-INSTALLED @huggingface/transformers version in the current
+// runtime, read from the resolved package's own package.json — NOT from
+// typeclaw's dependency spec (which is the intended version, not what is on
+// disk). The model-cache sentinel compares this across stages: the host
+// stamps the version that produced the download, the container checks the
+// version that will consume it. Comparing two intended constants would miss
+// exactly the drift this guards — "the installed runtime isn't what the build
+// said it should be" (e.g. a lockfile-free `bun add` resolving a newer
+// release). Resolution is isolated here so the package-internals access lives
+// in one place.
+//
+// We resolve the package's EXPORTED entry and walk up to its package.json,
+// rather than `require('@huggingface/transformers/package.json')`: that subpath
+// is not in the package's `exports` map (only `node`/`default`), so a strict
+// Node-exports resolver throws ERR_PACKAGE_PATH_NOT_EXPORTED. The main entry IS
+// exported, and its package.json is the nearest one above the resolved file.
+export function getResolvedTransformersVersion(): string {
+  const require = createRequire(import.meta.url)
+  const entry = require.resolve('@huggingface/transformers')
+  const version = readNearestPackageVersion(dirname(entry))
+  if (version === null) {
+    throw new Error('could not resolve @huggingface/transformers version from its package.json')
+  }
+  return version
+}
+
+function readNearestPackageVersion(startDir: string): string | null {
+  const root = parsePath(startDir).root
+  let dir = startDir
+  for (;;) {
+    const version = readPackageNameVersion(join(dir, 'package.json'))
+    if (version !== null) return version
+    if (dir === root) return null
+    dir = dirname(dir)
+  }
+}
+
+// Only accept the @huggingface/transformers package.json, never a nested
+// dependency's: the resolved entry can sit under dist/, and an intermediate
+// dir could in theory carry an unrelated package.json. Match on name.
+function readPackageNameVersion(pkgPath: string): string | null {
+  let parsed: { name?: unknown; version?: unknown }
+  try {
+    parsed = JSON.parse(readFileSync(pkgPath, 'utf8')) as { name?: unknown; version?: unknown }
+  } catch {
+    return null
+  }
+  if (parsed.name !== '@huggingface/transformers') return null
+  if (typeof parsed.version !== 'string' || parsed.version.length === 0) return null
+  return parsed.version
+}

package/src/plugin/types.ts

@@ -182,6 +182,9 @@ export type SessionTurnStartEvent = {
   agentDir: string
   userPrompt: string
   origin?: SessionOrigin
+  // Mutable ref: plugin writes retrieval results here; server/router reads after hook returns.
+  // Only populated when vector.enabled and injection plan is index mode.
+  retrievalContext?: { results: string }
 }
 
 export type SessionTurnEndEvent = {

package/src/portbroker/container-server.ts

@@ -2,6 +2,7 @@ import { readFile } from 'node:fs/promises'
 
 import type { ServerWebSocket } from 'bun'
 
+import type { ForwardRequestEvent } from './forward-request-bus'
 import { parseProcNetTcp } from './proc-net-tcp'
 import { decodeBytes, encodeBytes, type ContainerToHostd, type HostdToContainer, type StreamId } from './protocol'
 
@@ -23,6 +24,7 @@ export type ContainerBrokerOptions = {
   // to the host side. Without it, code that picks an in-container port has no
   // way to detect host-side EADDRINUSE collisions across containers.
   onForwardResult?: (event: ForwardResultEvent) => void
+  onForwardRequestSubscribe?: (cb: (event: ForwardRequestEvent) => void) => () => void
 }
 
 export type ForwardResultEvent =
@@ -72,6 +74,8 @@ export function createContainerBroker(opts: ContainerBrokerOptions): ContainerBr
   }
 
   const sessions = new WeakMap<BrokerSocket, SessionState>()
+  const sockets = new Set<BrokerSocket>()
+  const reserved = new Map<number, ForwardRequestEvent>()
 
   const send = (ws: BrokerSocket, msg: ContainerToHostd): void => {
     try {
@@ -98,6 +102,22 @@ export function createContainerBroker(opts: ContainerBrokerOptions): ContainerBr
     }
   }
 
+  const sendReservedRequest = (ws: BrokerSocket, request: ForwardRequestEvent): void => {
+    send(ws, {
+      type: 'port-forward-request',
+      targetPort: request.targetPort,
+      hostCandidates: request.hostCandidates,
+      ...(request.reason !== undefined ? { reason: request.reason } : {}),
+    })
+  }
+
+  opts.onForwardRequestSubscribe?.((event) => {
+    reserved.set(event.targetPort, event)
+    for (const ws of sockets) {
+      if (ws.data.authed) sendReservedRequest(ws, event)
+    }
+  })
+
   const tickWatcher = async (ws: BrokerSocket, state: SessionState): Promise<void> => {
     const next = await snapshotPorts()
     for (const [port, bindAddr] of next) {
@@ -158,6 +178,7 @@ export function createContainerBroker(opts: ContainerBrokerOptions): ContainerBr
   return {
     open(ws) {
       sessions.set(ws, { pollTimer: null, lastSnapshot: new Map(), upstreams: new Map() })
+      sockets.add(ws)
     },
 
     async message(ws, raw) {
@@ -187,6 +208,7 @@ export function createContainerBroker(opts: ContainerBrokerOptions): ContainerBr
         ws.data.authed = true
         log({ kind: 'authed' })
         send(ws, { type: 'broker-hello-ack' })
+        for (const request of reserved.values()) sendReservedRequest(ws, request)
         return
       }
 
@@ -252,6 +274,7 @@ export function createContainerBroker(opts: ContainerBrokerOptions): ContainerBr
         } catch {}
       }
       state.upstreams.clear()
+      sockets.delete(ws)
       sessions.delete(ws)
     },
   }

package/src/portbroker/forward-request-bus.ts

@@ -0,0 +1,35 @@
+// In-process event bus for explicit container→host forward requests. The
+// agent-browser plugin runs in the same process as the container broker but
+// does not hold a broker handle, so it publishes here and run/index wires the
+// bus into createContainerBroker.
+
+export type ForwardRequestEvent = {
+  targetPort: number
+  hostCandidates: number[]
+  reason?: string
+}
+
+type Subscriber = (event: ForwardRequestEvent) => void
+
+const subscribers = new Set<Subscriber>()
+
+export function publishForwardRequest(event: ForwardRequestEvent): void {
+  for (const sub of subscribers) {
+    try {
+      sub(event)
+    } catch {
+      // Subscriber failures must not block peer subscribers.
+    }
+  }
+}
+
+export function subscribeForwardRequest(cb: Subscriber): () => void {
+  subscribers.add(cb)
+  return () => {
+    subscribers.delete(cb)
+  }
+}
+
+export function __resetForwardRequestBus(): void {
+  subscribers.clear()
+}

package/src/portbroker/forward-result-bus.ts

@@ -1,9 +1,8 @@
 // In-process event bus for `port-forward-result` events emitted by the
 // host-side broker over the WS to the container side. Lives as a module-level
 // singleton so the run-loop wiring (src/run/index.ts) can publish events from
-// the broker callback while consumers (e.g. the agent-browser plugin's
-// bind-with-forward retry loop) subscribe by importing this module without
-// needing a reference to the ContainerBroker itself.
+// the broker callback while consumers subscribe by importing this module
+// without needing a reference to the ContainerBroker itself.
 //
 // Tests should call `__resetForwardResultBus()` in afterEach so subscriptions
 // from a previous test don't leak.

package/src/portbroker/hostd-client.ts

@@ -85,13 +85,21 @@ export function createBroker(opts: BrokerOptions): Broker {
   const listenHost = opts.listenHost ?? defaultListenHost
 
   type ForwarderState = {
-    port: number
+    targetPort: number
+    hostPort: number
     bindAddr: BindAddr
+    reserved: boolean
     listener: HostListener
     streams: Map<StreamId, { sock: HostSocket; opened: boolean; pending: Uint8Array[] }>
   }
 
   const forwarders = new Map<number, ForwarderState>()
+  const reservedTargets = new Map<number, number>()
+  // Targets claimed by a reserved forward whose host bind is still in flight.
+  // Marked synchronously BEFORE awaiting listenHost() so a concurrent
+  // port-listen snapshot/opened for the same target cannot slip past the
+  // reserved guard and install a competing auto-forward during the await.
+  const pendingReservedTargets = new Set<number>()
   let ws: WsClient | null = null
   let nextStreamId: StreamId = 1
   let stopped = false
@@ -112,8 +120,8 @@ export function createBroker(opts: BrokerOptions): Broker {
     }
   }
 
-  const closeStream = (port: number, streamId: StreamId, sendClose: boolean): void => {
-    const fwd = forwarders.get(port)
+  const closeStream = (hostPort: number, streamId: StreamId, sendClose: boolean): void => {
+    const fwd = forwarders.get(hostPort)
     if (!fwd) return
     const stream = fwd.streams.get(streamId)
     if (!stream) return
@@ -124,7 +132,7 @@ export function createBroker(opts: BrokerOptions): Broker {
     if (sendClose && ws) ws.send({ type: 'relay-close', streamId, side: 'downstream' })
   }
 
-  const handleHostConnection = (port: number, sock: HostSocket): void => {
+  const handleHostConnection = (hostPort: number, sock: HostSocket): void => {
     if (!ws) {
       try {
         sock.end()
@@ -132,7 +140,7 @@ export function createBroker(opts: BrokerOptions): Broker {
       return
     }
     const streamId = allocStreamId()
-    const fwd = forwarders.get(port)
+    const fwd = forwarders.get(hostPort)
     if (!fwd) {
       try {
         sock.end()
@@ -153,53 +161,174 @@ export function createBroker(opts: BrokerOptions): Broker {
       }
     })
     sock.onClose(() => {
-      closeStream(port, streamId, true)
+      closeStream(hostPort, streamId, true)
     })
 
-    if (ws) ws.send({ type: 'relay-open', streamId, port })
+    if (ws) ws.send({ type: 'relay-open', streamId, port: fwd.targetPort })
   }
 
-  const installForwarder = async (port: number, bindAddr: BindAddr): Promise<void> => {
-    if (forwarders.has(port)) return
-    if (!shouldForward({ policy: opts.policy, port })) {
-      // Policy excluded the port. Tell the container so it can stop waiting
-      // (e.g. the agent-browser plugin's bind-with-forward retry loop). Without
-      // this, the container would block on the forward-result timeout for
-      // every policy-denied port.
-      if (ws) ws.send({ type: 'port-forward-result', port, ok: false, reason: 'policy excluded' })
+  const isReservedTarget = (targetPort: number): boolean =>
+    reservedTargets.has(targetPort) || pendingReservedTargets.has(targetPort)
+
+  const hasAutoForwarderForTarget = (targetPort: number): boolean => {
+    for (const fwd of forwarders.values()) {
+      if (!fwd.reserved && fwd.targetPort === targetPort) return true
+    }
+    return false
+  }
+
+  const installForwarder = async (targetPort: number, bindAddr: BindAddr): Promise<void> => {
+    if (isReservedTarget(targetPort)) return
+    // Dedup by targetPort, not the map key: the map is keyed by the bound host
+    // port, which diverges from targetPort on an ephemeral bind, so a
+    // `forwarders.has(targetPort)` guard would miss an existing forward and bind
+    // a second host listener for the same container port.
+    if (hasAutoForwarderForTarget(targetPort)) return
+    if (!shouldForward({ policy: opts.policy, port: targetPort })) {
+      // Policy excluded the port. Tell the container so consumers waiting on
+      // port-forward-result can surface a diagnostic instead of hanging.
+      if (ws) ws.send({ type: 'port-forward-result', port: targetPort, ok: false, reason: 'policy excluded' })
       return
     }
     try {
-      const listener = await listenHost(hostBind, port, {
-        onConnection: (sock) => handleHostConnection(port, sock),
+      // The host listen port — not targetPort — is the forwarders map key, so
+      // the connection callback must look up by it. They coincide for ordinary
+      // 1:1 auto-forwards but diverge whenever the OS reassigns the bind (e.g. a
+      // port-0 ephemeral bind), at which point routing by targetPort misses the
+      // map and silently drops the connection. Captured after the await; a
+      // connection can only arrive once the listener is bound.
+      let boundHostPort: number | undefined
+      const listener = await listenHost(hostBind, targetPort, {
+        onConnection: (sock) => {
+          if (boundHostPort === undefined) {
+            try {
+              sock.end()
+            } catch {}
+            return
+          }
+          handleHostConnection(boundHostPort, sock)
+        },
+      })
+      boundHostPort = listener.port
+      forwarders.set(boundHostPort, {
+        targetPort,
+        hostPort: boundHostPort,
+        bindAddr,
+        reserved: false,
+        listener,
+        streams: new Map(),
       })
-      forwarders.set(port, { port, bindAddr, listener, streams: new Map() })
-      emit({ kind: 'port-forward-opened', containerName: opts.containerName, port, bindAddr })
-      if (ws) ws.send({ type: 'port-forward-result', port, ok: true, hostPort: listener.port })
+      emit({
+        kind: 'port-forward-opened',
+        containerName: opts.containerName,
+        port: targetPort,
+        hostPort: boundHostPort,
+        bindAddr,
+      })
+      if (ws) ws.send({ type: 'port-forward-result', port: targetPort, ok: true, hostPort: boundHostPort })
     } catch (err) {
       const reason = err instanceof Error ? err.message : String(err)
-      log(`forward bind ${port}: ${reason}`)
-      emit({ kind: 'port-forward-failed', containerName: opts.containerName, port, reason })
-      if (ws) ws.send({ type: 'port-forward-result', port, ok: false, reason })
+      log(`forward bind ${targetPort}: ${reason}`)
+      emit({ kind: 'port-forward-failed', containerName: opts.containerName, port: targetPort, reason })
+      if (ws) ws.send({ type: 'port-forward-result', port: targetPort, ok: false, reason })
+    }
+  }
+
+  const installReservedForwarder = async (targetPort: number, hostCandidates: number[]): Promise<void> => {
+    const existingHostPort = reservedTargets.get(targetPort)
+    if (existingHostPort !== undefined) {
+      if (ws) ws.send({ type: 'port-forward-result', port: targetPort, ok: true, hostPort: existingHostPort })
+      return
+    }
+    if (!shouldForward({ policy: opts.policy, port: targetPort })) {
+      if (ws) ws.send({ type: 'port-forward-result', port: targetPort, ok: false, reason: 'policy excluded' })
+      return
+    }
+
+    // Claim the target and evict any auto-forward that already won the race
+    // before the reserved bind below yields control to the event loop.
+    pendingReservedTargets.add(targetPort)
+    removeAutoForwarderForTarget(targetPort, 'container-released')
+
+    let lastReason = 'no host candidates'
+    for (const hostPort of hostCandidates) {
+      try {
+        // `port` stays the in-container target; the host listen port is the
+        // forwarders map key the connection callback must route by. Reserved
+        // forwards deliberately allow the two to differ, so route by the actual
+        // bound port, captured after the await.
+        let boundHostPort: number | undefined
+        const listener = await listenHost(hostBind, hostPort, {
+          onConnection: (sock) => {
+            if (boundHostPort === undefined) {
+              try {
+                sock.end()
+              } catch {}
+              return
+            }
+            handleHostConnection(boundHostPort, sock)
+          },
+        })
+        boundHostPort = listener.port
+        forwarders.set(boundHostPort, {
+          targetPort,
+          hostPort: boundHostPort,
+          bindAddr: '127.0.0.1',
+          reserved: true,
+          listener,
+          streams: new Map(),
+        })
+        reservedTargets.set(targetPort, boundHostPort)
+        pendingReservedTargets.delete(targetPort)
+        emit({
+          kind: 'port-forward-opened',
+          containerName: opts.containerName,
+          port: targetPort,
+          hostPort: boundHostPort,
+          bindAddr: '127.0.0.1',
+        })
+        if (ws) ws.send({ type: 'port-forward-result', port: targetPort, ok: true, hostPort: boundHostPort })
+        return
+      } catch (err) {
+        lastReason = err instanceof Error ? err.message : String(err)
+        log(`reserved forward bind ${hostPort} for ${targetPort}: ${lastReason}`)
+      }
     }
+    pendingReservedTargets.delete(targetPort)
+    emit({ kind: 'port-forward-failed', containerName: opts.containerName, port: targetPort, reason: lastReason })
+    if (ws) ws.send({ type: 'port-forward-result', port: targetPort, ok: false, reason: lastReason })
   }
 
-  const removeForwarder = (port: number, reason: 'container-released' | 'host-error'): void => {
-    const fwd = forwarders.get(port)
+  const removeForwarder = (hostPort: number, reason: 'container-released' | 'host-error'): void => {
+    const fwd = forwarders.get(hostPort)
     if (!fwd) return
-    forwarders.delete(port)
+    forwarders.delete(hostPort)
+    if (fwd.reserved) reservedTargets.delete(fwd.targetPort)
     try {
       fwd.listener.stop()
     } catch {}
-    for (const [streamId] of fwd.streams) closeStream(port, streamId, false)
-    emit({ kind: 'port-forward-closed', containerName: opts.containerName, port, reason })
+    for (const [streamId] of fwd.streams) closeStream(hostPort, streamId, false)
+    emit({
+      kind: 'port-forward-closed',
+      containerName: opts.containerName,
+      port: fwd.targetPort,
+      hostPort: fwd.hostPort,
+      reason,
+    })
+  }
+
+  const removeAutoForwarderForTarget = (targetPort: number, reason: 'container-released' | 'host-error'): void => {
+    for (const [hostPort, fwd] of Array.from(forwarders)) {
+      if (!fwd.reserved && fwd.targetPort === targetPort) removeForwarder(hostPort, reason)
+    }
   }
 
   const teardownAllForwarders = (reason: 'broker-stopped' | 'deregistered' | 'host-error'): void => {
-    for (const port of Array.from(forwarders.keys())) {
-      const fwd = forwarders.get(port)
+    for (const hostPort of Array.from(forwarders.keys())) {
+      const fwd = forwarders.get(hostPort)
       if (!fwd) continue
-      forwarders.delete(port)
+      forwarders.delete(hostPort)
+      if (fwd.reserved) reservedTargets.delete(fwd.targetPort)
       try {
         fwd.listener.stop()
       } catch {}
@@ -209,7 +338,19 @@ export function createBroker(opts: BrokerOptions): Broker {
           stream?.sock.end()
         } catch {}
       }
-      emit({ kind: 'port-forward-closed', containerName: opts.containerName, port, reason })
+      emit({
+        kind: 'port-forward-closed',
+        containerName: opts.containerName,
+        port: fwd.targetPort,
+        hostPort: fwd.hostPort,
+        reason,
+      })
+    }
+  }
+
+  const teardownAutoForwarders = (reason: 'host-error'): void => {
+    for (const [hostPort, fwd] of Array.from(forwarders)) {
+      if (!fwd.reserved) removeForwarder(hostPort, reason)
     }
   }
 
@@ -228,14 +369,19 @@ export function createBroker(opts: BrokerOptions): Broker {
         return
       case 'port-listen-snapshot':
         for (const { port, bindAddr } of msg.ports) {
-          void installForwarder(port, bindAddr)
+          if (!isReservedTarget(port)) void installForwarder(port, bindAddr)
         }
         return
       case 'port-listen-opened':
+        if (isReservedTarget(msg.port)) return
         void installForwarder(msg.port, msg.bindAddr)
         return
       case 'port-listen-closed':
-        removeForwarder(msg.port, 'container-released')
+        if (isReservedTarget(msg.port)) return
+        removeAutoForwarderForTarget(msg.port, 'container-released')
+        return
+      case 'port-forward-request':
+        void installReservedForwarder(msg.targetPort, msg.hostCandidates)
         return
       case 'relay-open-ack': {
         const port = findStreamPort(msg.streamId)
@@ -303,7 +449,7 @@ export function createBroker(opts: BrokerOptions): Broker {
     client.onMessage(handleContainerMessage)
     client.onClose(() => {
       ws = null
-      teardownAllForwarders('host-error')
+      teardownAutoForwarders('host-error')
       scheduleReconnect()
     })
 
@@ -404,7 +550,7 @@ async function defaultConnectWs(url: string): Promise<WsClient> {
   })
 }
 
-function defaultListenHost(
+export function defaultListenHost(
   host: string,
   port: number,
   handlers: { onConnection: (sock: HostSocket) => void },

package/src/portbroker/index.ts

@@ -20,8 +20,13 @@ export {
   type UpstreamConnection,
   type UpstreamHandlers,
 } from './container-server'
+export {
+  __resetForwardRequestBus,
+  publishForwardRequest,
+  subscribeForwardRequest,
+  type ForwardRequestEvent,
+} from './forward-request-bus'
 export { __resetForwardResultBus, publishForwardResult, subscribeForwardResult } from './forward-result-bus'
-export { bindWithForward, type BindFactory, type BindResult, type BindWithForwardOptions } from './bind-with-forward'
 export {
   createBroker,
   type Broker,