threadwire 0.1.6 → 0.1.8

package/src/isolated-runtime.js

@@ -0,0 +1,982 @@
+// @ts-nocheck
+/* eslint-disable jsdoc/require-jsdoc */
+
+import {randomBytes} from "node:crypto"
+import {lstat, realpath} from "node:fs/promises"
+import {createServer} from "node:http"
+import {isAbsolute, join, normalize, relative} from "node:path"
+import {DockerApi} from "./docker-api.js"
+import {buildWorkerContainerSpec, isDigestImage} from "./isolated-worker.js"
+import {validateRelayWriteProviderArguments} from "./relay-write.js"
+import {codexSessionId, parseCodexEvent} from "./providers/codex.js"
+import {openStateRegistry, validateStateVolume} from "./isolated-state.js"
+import {assertNoNestedMounts} from "./mount-policy.js"
+import {AbsoluteDeadline, deadlineAfter} from "./absolute-deadline.js"
+
+const MAX_PREFLIGHT_BYTES = 32_768
+const MAX_RUN_BYTES = 1_048_576
+const PREFLIGHT_TTL_MS = 60_000
+const PREFLIGHT_CAPACITY = 128
+const PREFLIGHT_TASK_CAPACITY = 8
+const GC_INTERVAL_MS = 5_000
+const ACTIVE_RUN_CAPACITY = 16
+const ACTIVE_TASK_CAPACITY = 2
+const WORKER_TIMEOUT_MS = 3_600_000
+const PREFLIGHT_TIMEOUT_MS = 30_000
+const MAX_RAW_OUTPUT_BYTES = 1_048_576
+
+/** @param {{environment?: NodeJS.ProcessEnv, docker?: DockerApi, fetchImplementation?: typeof fetch, now?: () => number}} [options] */
+export async function startIsolatedRuntime(options = {}) {
+  const environment = options.environment ?? process.env
+  const host = environment.THREADWIRE_ISOLATED_RUNTIME_HOST ?? "0.0.0.0"
+  const port = portValue(environment.THREADWIRE_ISOLATED_RUNTIME_PORT, 8790)
+  const controlToken = safeSetting(environment.THREADWIRE_ISOLATED_RUNTIME_CONTROL_TOKEN, "THREADWIRE_ISOLATED_RUNTIME_CONTROL_TOKEN")
+  const workerImage = safeSetting(environment.THREADWIRE_RELAY_WORKER_IMAGE, "THREADWIRE_RELAY_WORKER_IMAGE")
+  if (!isDigestImage(workerImage)) throw new Error("THREADWIRE_RELAY_WORKER_IMAGE must use an immutable digest")
+  const brokerUrl = normalizedHttpUrl(environment.THREADWIRE_MODEL_BROKER_URL, "THREADWIRE_MODEL_BROKER_URL")
+  const brokerAdminToken = safeSetting(environment.THREADWIRE_MODEL_BROKER_ADMIN_TOKEN, "THREADWIRE_MODEL_BROKER_ADMIN_TOKEN")
+  const brokerContainer = safeSetting(environment.THREADWIRE_MODEL_BROKER_CONTAINER, "THREADWIRE_MODEL_BROKER_CONTAINER")
+  const allowedRoots = parseAllowedRoots(environment.THREADWIRE_ALLOWED_WORKTREE_ROOTS)
+  const worktreeVolume = environment.THREADWIRE_WORKTREE_VOLUME
+  const sessionTtlMs = positiveDuration(environment.THREADWIRE_SESSION_TTL_MS, 86_400_000)
+  const workerTimeoutMs = positiveDuration(environment.THREADWIRE_WORKER_TIMEOUT_MS, WORKER_TIMEOUT_MS)
+  const preflightTimeoutMs = positiveDuration(environment.THREADWIRE_PREFLIGHT_TIMEOUT_MS, PREFLIGHT_TIMEOUT_MS)
+  const docker = options.docker ?? new DockerApi()
+  const fetchImplementation = options.fetchImplementation ?? fetch
+  const now = options.now ?? Date.now
+  const allowedModels = parseAllowedModels(environment.THREADWIRE_ALLOWED_CODEX_MODELS)
+  const stateRegistry = await openStateRegistry({
+    file: safeSetting(environment.THREADWIRE_STATE_REGISTRY_FILE, "THREADWIRE_STATE_REGISTRY_FILE"),
+    key: safeSetting(environment.THREADWIRE_STATE_AUTH_KEY, "THREADWIRE_STATE_AUTH_KEY"),
+    namespace: safeSetting(environment.THREADWIRE_STATE_NAMESPACE, "THREADWIRE_STATE_NAMESPACE"),
+    now
+  })
+  const preflights = new PreflightStore({
+    now,
+    ttlMs: options.preflightTtlMs ?? PREFLIGHT_TTL_MS,
+    capacity: options.preflightCapacity ?? PREFLIGHT_CAPACITY,
+    taskCapacity: options.preflightTaskCapacity ?? PREFLIGHT_TASK_CAPACITY
+  })
+  const activeLineages = new LineageReservations()
+  const activeRuns = new ActiveRunAdmission({
+    capacity: positiveInteger(environment.THREADWIRE_ACTIVE_RUN_CAPACITY, ACTIVE_RUN_CAPACITY),
+    taskCapacity: positiveInteger(environment.THREADWIRE_ACTIVE_TASK_CAPACITY, ACTIVE_TASK_CAPACITY)
+  })
+  const incomingRequests = new ActiveRunAdmission({capacity: ACTIVE_RUN_CAPACITY, taskCapacity: ACTIVE_RUN_CAPACITY})
+  const shutdown = new AbortController()
+  const sockets = new Set()
+  let stopping = false
+  let gcPromise = Promise.resolve()
+  const collectState = () => {
+    gcPromise = gcPromise.then(async () => {
+      if (shutdown.signal.aborted) return
+      const collection = deadlineAfter(Math.min(30_000, workerTimeoutMs), {signal: shutdown.signal, timeoutMessage: "Isolated runtime collection timeout"})
+      const releaseCollection = activeLineages.beginCollection()
+      try {
+        const active = new Set(activeLineages.values())
+        const current = {
+          *[Symbol.iterator]() { yield * active },
+          has(lineage) { return active.has(lineage) || activeLineages.has(lineage) }
+        }
+        for (const lineage of await reconcileDockerResources(docker, brokerContainer, stateRegistry, current, collection.options())) active.add(lineage)
+        await stateRegistry.collect(docker, {has: (lineage) => active.has(lineage) || activeLineages.has(lineage)}, collection.options())
+      } finally {
+        collection.close()
+        releaseCollection()
+      }
+    }).catch(() => {})
+    return gcPromise
+  }
+  const startupActive = await reconcileDockerResources(docker, brokerContainer, stateRegistry, new Set())
+  await stateRegistry.collect(docker, new Set(startupActive))
+  const gcTimer = setInterval(collectState, Math.min(GC_INTERVAL_MS, sessionTtlMs))
+  gcTimer.unref()
+
+  const server = createServer(async (request, response) => {
+    try {
+      if (stopping) throw new Error("Isolated runtime is shutting down")
+      requireControl(request.headers.authorization, controlToken)
+      if (request.method === "GET" && request.url === "/healthz") {
+        sendJson(response, 200, {ok: true})
+        return
+      }
+      if (request.method === "POST" && request.url === "/preflight") {
+        const releaseIncoming = incomingRequests.acquire("preflight")
+        const launchDeadlineAt = requestedDeadline(request.headers["x-threadwire-launch-deadline"], workerTimeoutMs)
+        const operation = new AbsoluteDeadline(Math.min(Date.now() + preflightTimeoutMs, launchDeadlineAt), {
+          signal: shutdown.signal, request, response, timeoutMessage: "Isolated runtime operation timed out", disconnectMessage: "Isolated runtime caller disconnected"
+        })
+        try {
+          const body = await readJson(request, MAX_PREFLIGHT_BYTES, operation.signal)
+          const selection = parsePreflight(body)
+          const task = taskIdentity(selection)
+          preflights.assertCapacity(task)
+          let codexArguments
+          try {
+            codexArguments = validateRelayWriteProviderArguments(selection.providerArguments)
+          } catch (error) {
+            throw new ClientError(error instanceof Error ? error.message : "Provider argument is unavailable in relay write mode")
+          }
+          if (!allowedModels.has(codexArguments.model)) throw new ClientError("Codex model is not allowed")
+          const {fingerprint, root: worktreeRoot} = await verifyPrerequisites({
+            docker, workerImage, selection, allowedRoots, brokerUrl, brokerAdminToken, fetchImplementation, operation
+          })
+          let state
+          if (selection.resumeSession !== undefined) {
+            state = stateRegistry.lookup(selection.resumeSession)
+            if (!state || state.task !== task) throw new ClientError("Codex resume state is unavailable")
+            const volume = await docker.inspectVolume(state.volume, operation.options()).catch(() => undefined)
+            try { validateStateVolume(volume, state.volume, state.labels) } catch { throw new ClientError("Codex resume state is unavailable") }
+          } else state = stateRegistry.allocate(task)
+          const preflightId = randomBytes(24).toString("base64url")
+          preflights.add(preflightId, task, {...selection, codexArguments, state, fingerprint, worktreeRoot, launchDeadlineAt})
+          sendJson(response, 200, {ok: true, preflightId, launchDeadlineAt})
+        } finally {
+          operation.close()
+          releaseIncoming()
+        }
+        return
+      }
+      if (request.method === "POST" && request.url === "/run") {
+        const releaseIncoming = incomingRequests.acquire("run")
+        const bodyOperation = new AbsoluteDeadline(Date.now() + preflightTimeoutMs, {signal: shutdown.signal, request, response, timeoutMessage: "Isolated runtime operation timed out"})
+        let body
+        try {
+          body = parseRun(await readJson(request, MAX_RUN_BYTES, bodyOperation.signal))
+        } finally {
+          bodyOperation.close()
+          releaseIncoming()
+        }
+        const preflight = preflights.consume(body.preflightId)
+        if (!preflight) throw new ClientError("Isolated runtime preflight expired")
+        const operation = new AbsoluteDeadline(Math.min(preflight.launchDeadlineAt,
+          requestedDeadline(request.headers["x-threadwire-launch-deadline"], workerTimeoutMs)), {
+          signal: shutdown.signal, request, response, timeoutMessage: "Isolated runtime launch timed out", disconnectMessage: "Isolated runtime caller disconnected"
+        })
+        const task = taskIdentity(preflight)
+        let releaseRun
+        let releaseLineage
+        try {
+          releaseRun = activeRuns.acquire(task)
+          releaseLineage = activeLineages.acquire(preflight.state.lineage)
+          if (body.resumeSession !== preflight.resumeSession) throw new ClientError("Codex resume state does not match preflight")
+          if (JSON.stringify(validateRelayWriteProviderArguments(body.providerArguments)) !== JSON.stringify(preflight.codexArguments)) {
+            throw new ClientError("Codex arguments do not match preflight")
+          }
+          await revalidateFingerprint(preflight.fingerprint)
+          operation.throwIfAborted()
+          const result = await runIsolatedWorker({
+            docker, workerImage, brokerUrl, brokerAdminToken, brokerContainer,
+            fetchImplementation, preflight, ...body, task, now, stateRegistry, sessionTtlMs, operation,
+            ...(worktreeVolume === undefined ? {} : {worktreeVolume})
+          })
+          sendJson(response, 200, result)
+        } finally {
+          operation.close()
+          releaseLineage?.()
+          releaseRun?.()
+          void collectState()
+        }
+        return
+      }
+      response.writeHead(404)
+      response.end()
+    } catch (error) {
+      sendJson(response, error instanceof ClientError ? 400 : 503, {
+        error: error instanceof ClientError ? error.message : "Isolated runtime unavailable"
+      })
+    }
+  })
+  server.on("connection", (socket) => {
+    sockets.add(socket)
+    socket.once("close", () => sockets.delete(socket))
+  })
+  await listen(server, port, host)
+  return {
+    server,
+    close: async () => {
+      stopping = true
+      clearInterval(gcTimer)
+      preflights.close()
+      shutdown.abort(new Error("Isolated runtime is shutting down"))
+      for (const socket of sockets) socket.destroy()
+      await boundedClose(server, 1000)
+      await Promise.race([gcPromise, new Promise((resolve) => setTimeout(resolve, 1000))])
+    },
+    config: {host, port}
+  }
+}
+
+async function verifyPrerequisites(options) {
+  const {docker, workerImage, selection, allowedRoots, brokerUrl, brokerAdminToken, fetchImplementation, operation} = options
+  const version = /** @type {{ApiVersion?: unknown}} */ (await docker.version(operation.options()))
+  if (typeof version.ApiVersion !== "string") throw new Error("Docker API unavailable")
+  const image = /** @type {{Id?: unknown}} */ (await docker.inspectImage(workerImage, operation.options()))
+  if (typeof image.Id !== "string" || !isDigestImage(image.Id)) throw new Error("Worker image unavailable")
+  const validatedWorktree = await validateWorktreeSelection(selection.repositoryRoot, selection.cwd, allowedRoots)
+  const health = await abortable(fetchImplementation(new URL("/healthz", brokerUrl), {
+    method: "GET",
+    redirect: "error",
+    signal: operation.signal,
+    headers: {authorization: `Bearer ${brokerAdminToken}`}
+  }), operation.signal)
+  if (!health.ok) throw new Error("Model broker unavailable")
+  return validatedWorktree
+}
+
+export async function validateWorktree(repositoryRoot, cwd, allowedRoots) {
+  return (await validateWorktreeSelection(repositoryRoot, cwd, allowedRoots)).fingerprint
+}
+
+export async function validateWorktreeSelection(repositoryRoot, cwd, allowedRoots) {
+  const root = allowedRoots
+    .filter((allowed) => within(allowed, repositoryRoot))
+    .sort((first, second) => second.length - first.length)[0]
+  if (root === undefined) throw new ClientError("Configured worktree is unavailable")
+  const paths = ancestry(root, repositoryRoot)
+  for (const path of ancestry(repositoryRoot, cwd).slice(1)) if (!paths.includes(path)) paths.push(path)
+  /** @type {{path: string, dev: string, ino: string}[]} */
+  const fingerprint = []
+  for (const path of paths) {
+    if (!isAbsolute(path) || normalize(path) !== path || path === "/") throw new ClientError("Configured worktree is unavailable")
+    const metadata = await lstat(path, {bigint: true})
+    if (!metadata.isDirectory() || metadata.isSymbolicLink() || await realpath(path) !== path) {
+      throw new ClientError("Configured worktree is unavailable")
+    }
+    fingerprint.push({path, dev: String(metadata.dev), ino: String(metadata.ino)})
+  }
+  if (!within(repositoryRoot, cwd) || !allowedRoots.some((allowed) => within(allowed, repositoryRoot))) {
+    throw new ClientError("Configured worktree is unavailable")
+  }
+  await assertNoNestedMounts(repositoryRoot)
+  try {
+    const gitEntry = await lstat(join(repositoryRoot, ".git"))
+    if (gitEntry.isDirectory()) throw new ClientError("Common Git directories cannot enter the worker")
+    if (!gitEntry.isFile() || gitEntry.isSymbolicLink()) throw new ClientError("Configured worktree is unavailable")
+  } catch (error) {
+    if (error instanceof ClientError) throw error
+    if (/** @type {NodeJS.ErrnoException} */ (error).code !== "ENOENT") throw error
+  }
+  return {fingerprint, root}
+}
+
+export async function revalidateFingerprint(fingerprint) {
+  if (!Array.isArray(fingerprint)) throw new ClientError("Configured worktree changed after preflight")
+  for (const expected of fingerprint) {
+    const metadata = await lstat(expected.path, {bigint: true}).catch(() => undefined)
+    if (!metadata?.isDirectory() || metadata.isSymbolicLink() || String(metadata.dev) !== expected.dev || String(metadata.ino) !== expected.ino || await realpath(expected.path) !== expected.path) {
+      throw new ClientError("Configured worktree changed after preflight")
+    }
+  }
+}
+
+export async function runIsolatedWorker(options) {
+  const runId = `tw-${randomBytes(12).toString("hex")}`
+  const networkName = `${runId}-net`
+  const state = options.preflight.state
+  const freshState = options.resumeSession === undefined
+  let keepFreshState = false
+  let networkId
+  let containerId
+  let grantToken
+  let runTracked = false
+  const operation = options.operation
+  const worktreeSubpath = options.worktreeVolume === undefined
+    ? ""
+    : deriveVolumeWorktreeSubpath(options.preflight.worktreeRoot, options.preflight.repositoryRoot)
+  try {
+    operation.throwIfAborted()
+    await prepareStateVolume(options.docker, state, freshState, operation.options())
+    if (freshState) await options.stateRegistry.track(state, operation.signal)
+    const runIdentity = expectedRunIdentity(options, runId, networkName, state, worktreeSubpath)
+    const runSeal = options.stateRegistry.sealRun(runIdentity)
+    await options.stateRegistry.trackRun(runIdentity, operation.signal)
+    runTracked = true
+    const resourceLabels = {
+      "org.threadwire.namespace": options.stateRegistry.namespace,
+      "org.threadwire.run": runId,
+      "org.threadwire.lineage": state.lineage,
+      "org.threadwire.task": state.labels["org.threadwire.task"],
+      "org.threadwire.state-volume": state.volume,
+      "org.threadwire.run-seal": runSeal
+    }
+    const network = /** @type {{Id?: unknown}} */ (await options.docker.createNetwork(networkName, resourceLabels, operation.options()))
+    if (typeof network.Id !== "string") throw new Error("Docker network creation failed")
+    networkId = network.Id
+    await options.docker.connectNetwork(networkId, options.brokerContainer, [], operation.options())
+    const networkInspection = await options.docker.inspectNetwork(networkId, operation.options())
+    const brokerAddress = brokerNetworkAddress(networkInspection, options.brokerContainer)
+    const grantResponse = await abortable(options.fetchImplementation(new URL("/admin/grants", options.brokerUrl), {
+      method: "POST",
+      redirect: "error",
+      signal: operation.signal,
+      headers: {authorization: `Bearer ${options.brokerAdminToken}`, "content-type": "application/json"},
+      body: JSON.stringify({runId, provider: "codex", networkId, model: options.preflight.codexArguments.model, brokerAddress, ttlMs: Math.min(operation.remaining(), 3_600_000)})
+    }), operation.signal)
+    if (!grantResponse.ok) throw new Error("Model broker grant failed")
+    const grant = await grantResponse.json()
+    if (!isRecord(grant) || typeof grant.token !== "string" || !Number.isSafeInteger(grant.port)) throw new Error("Model broker grant failed")
+    grantToken = grant.token
+    const repository = /** @type {{path: string, ino: string}[]} */ (options.preflight.fingerprint)
+    const worktreeMetadata = repository.find((entry) => entry.path === options.preflight.repositoryRoot)
+    const cwdMetadata = repository.find((entry) => entry.path === options.preflight.cwd)
+    if (worktreeMetadata === undefined || cwdMetadata === undefined) throw new Error("Worktree fingerprint unavailable")
+    const spec = buildWorkerContainerSpec({
+      image: options.workerImage,
+      worktree: options.preflight.repositoryRoot,
+      networkName,
+      brokerToken: grantToken,
+      brokerUrl: `http://${brokerAddress}:${grant.port}/v1`,
+      prompt: options.prompt,
+      providerArguments: options.preflight.codexArguments.arguments,
+      stateVolume: state.volume,
+      workingDirectory: `/worktree${relative(options.preflight.repositoryRoot, options.preflight.cwd) === "" ? "" : `/${relative(options.preflight.repositoryRoot, options.preflight.cwd)}`}`,
+      worktreeInode: worktreeMetadata.ino,
+      cwdInode: cwdMetadata.ino,
+      lineage: state.lineage,
+      namespace: options.stateRegistry.namespace,
+      runId,
+      taskHash: state.labels["org.threadwire.task"],
+      runSeal,
+      ...(options.worktreeVolume === undefined
+        ? {}
+        : {
+          worktreeVolume: {
+            name: options.worktreeVolume,
+            subpath: worktreeSubpath
+          }
+        }),
+      ...(options.resumeSession === undefined ? {} : {resumeSession: options.resumeSession})
+    })
+    const container = /** @type {{Id?: unknown}} */ (await options.docker.createContainer(`${runId}-worker`, spec, operation.options()))
+    if (typeof container.Id !== "string") throw new Error("Docker worker creation failed")
+    containerId = container.Id
+    await revalidateFingerprint(options.preflight.fingerprint)
+    await validateWorkerMountInventory(await options.docker.inspectContainer(containerId, operation.options()), spec.HostConfig.Mounts)
+    const activationResponse = await abortable(options.fetchImplementation(
+      new URL(`/admin/grants/${encodeURIComponent(grantToken)}/activate`, options.brokerUrl), {
+        method: "POST",
+        redirect: "error",
+        signal: operation.signal,
+        headers: {authorization: `Bearer ${options.brokerAdminToken}`}
+      }), operation.signal)
+    if (!activationResponse.ok) throw new Error("Model broker grant activation failed")
+    await options.docker.startContainer(containerId, operation.options())
+    const wait = /** @type {{StatusCode?: unknown}} */ (await options.docker.waitContainer(containerId, operation.options()))
+    const logs = /** @type {Buffer} */ (await options.docker.logs(containerId, operation.options()))
+    const rawChunks = demultiplexDockerLogChunks(logs)
+    const result = {
+      exitCode: typeof wait.StatusCode === "number" ? wait.StatusCode : 1,
+      records: parseWorkerRecords(Buffer.concat(rawChunks.filter((chunk) => chunk.channel === "stdout").map((chunk) => chunk.data)).toString("utf8")),
+      rawChunks: rawChunks.map((chunk) => ({channel: chunk.channel, data: chunk.data.toString("base64")}))
+    }
+    if (freshState && result.exitCode === 0) {
+      const sessionIds = [...new Set(result.records.filter((record) => record.type === "session").map((record) => record.sessionId))]
+      if (sessionIds.length === 0) throw new Error("Codex session state was not established")
+      await options.stateRegistry.register(sessionIds, state, options.sessionTtlMs, operation.signal)
+      keepFreshState = true
+    }
+    return result
+  } finally {
+    let resourcesRemoved = true
+    // A caller/deadline abort cannot authorize more work, but exact force
+    // teardown must remain possible. This supervisor-only emergency budget is
+    // bounded and is used solely for already-recorded resource identifiers.
+    const emergencyCleanup = operation.signal.aborted
+      ? deadlineAfter(5_000, {timeoutMessage: "Isolated runtime emergency cleanup timeout"})
+      : undefined
+    const cleanupOperation = emergencyCleanup ?? operation
+    const cleanupOptions = () => cleanupOperation.options()
+    if (grantToken !== undefined) {
+      await abortable(options.fetchImplementation(new URL(`/admin/grants/${encodeURIComponent(grantToken)}`, options.brokerUrl), {
+        method: "DELETE",
+        signal: cleanupOperation.signal,
+        headers: {authorization: `Bearer ${options.brokerAdminToken}`}
+      }), cleanupOperation.signal).catch(() => process.stderr.write("threadwire-isolated-runtime: grant cleanup failed\n"))
+    }
+    if (containerId !== undefined) await cleanupDocker(() => options.docker.removeContainer(containerId, cleanupOptions())).catch(() => {
+      resourcesRemoved = false
+      process.stderr.write("threadwire-isolated-runtime: worker cleanup failed\n")
+    })
+    if (networkId !== undefined) {
+      await cleanupDocker(() => options.docker.disconnectNetwork(networkId, options.brokerContainer, cleanupOptions())).catch(() => {})
+      await cleanupDocker(() => options.docker.removeNetwork(networkId, cleanupOptions())).catch(() => {
+        resourcesRemoved = false
+        process.stderr.write("threadwire-isolated-runtime: network cleanup failed\n")
+      })
+    }
+    if (freshState && !keepFreshState) await cleanupDocker(() => options.docker.removeVolume(state.volume, cleanupOptions())).catch(() => { resourcesRemoved = false })
+    if (runTracked && resourcesRemoved) await options.stateRegistry.completeRun(runId, cleanupOperation.signal).catch(() => {})
+    emergencyCleanup?.close()
+  }
+}
+
+async function cleanupDocker(operation) {
+  return operation()
+}
+
+export async function prepareStateVolume(docker, state, fresh, requestOptions) {
+  if (fresh) await docker.createVolume(state.volume, state.labels, requestOptions)
+  const volume = await docker.inspectVolume(state.volume, requestOptions).catch(() => undefined)
+  try {
+    validateStateVolume(volume, state.volume, state.labels)
+  } catch {
+    throw new ClientError(fresh ? "Codex state volume collision" : "Codex resume state is unavailable")
+  }
+}
+
+export function validateWorkerMountInventory(container, expected) {
+  if (!isRecord(container) || !Array.isArray(container.Mounts) || container.Mounts.length !== expected.length) {
+    throw new Error("Worker mount topology unavailable")
+  }
+  for (const mount of expected) {
+    const actual = container.Mounts.find((entry) => isRecord(entry) && entry.Destination === mount.Target)
+    const sourceMatches = mount.Type === "volume" ? actual?.Name === mount.Source : actual?.Source === mount.Source
+    if (!actual || actual.Type !== mount.Type || !sourceMatches || actual.RW !== !mount.ReadOnly) {
+      throw new Error("Worker mount topology unavailable")
+    }
+  }
+}
+
+function parseWorkerRecords(text) {
+  const records = []
+  for (const line of text.split("\n")) {
+    if (line.trim().length === 0) continue
+    try {
+      const record = JSON.parse(line)
+      if (isRecord(record)) {
+        records.push(record)
+        if (record.type !== "worker-event") {
+          const sessionId = codexSessionId(record)
+          if (sessionId !== undefined) records.push({type: "session", sessionId})
+          for (const event of parseCodexEvent(record)) records.push({type: "worker-event", event})
+        }
+      }
+    } catch {
+      records.push({type: "worker-event", event: {type: "diagnostic", level: "warning", summary: "Worker emitted an unreadable event"}})
+    }
+  }
+  return records
+}
+
+export function demultiplexDockerLogs(buffer) {
+  return Buffer.concat(demultiplexDockerLogChunks(buffer).map((chunk) => chunk.data)).toString("utf8")
+}
+
+export function demultiplexDockerLogChunks(buffer) {
+  let offset = 0
+  const output = []
+  let bytes = 0
+  while (offset + 8 <= buffer.length) {
+    const stream = buffer[offset]
+    const length = buffer.readUInt32BE(offset + 4)
+    if ((stream !== 1 && stream !== 2) || offset + 8 + length > buffer.length) throw new Error("Worker emitted invalid Docker logs")
+    bytes += length
+    if (bytes > MAX_RAW_OUTPUT_BYTES) throw new Error("Worker output exceeded capacity")
+    output.push({channel: stream === 1 ? "stdout" : "stderr", data: buffer.subarray(offset + 8, offset + 8 + length)})
+    offset += 8 + length
+  }
+  if (offset === buffer.length && output.length > 0) return output
+  if (buffer.length > MAX_RAW_OUTPUT_BYTES) throw new Error("Worker output exceeded capacity")
+  return [{channel: "stdout", data: buffer}]
+}
+
+export function parsePreflight(value) {
+  if (!isRecord(value) || value.provider !== "codex" || typeof value.profile !== "string" || typeof value.repositoryRoot !== "string" || typeof value.cwd !== "string" || !Array.isArray(value.providerArguments) || !value.providerArguments.every((item) => typeof item === "string")) {
+    throw new ClientError("Invalid isolated runtime preflight")
+  }
+  if (!bounded(value.profile, 128) || !bounded(value.repositoryRoot, 4096) || !bounded(value.cwd, 4096)
+    || value.providerArguments.length > 16 || value.providerArguments.some((item) => !bounded(item, 512))
+    || (value.resumeSession !== undefined && !bounded(value.resumeSession, 256))) {
+    throw new ClientError("Invalid isolated runtime preflight")
+  }
+  if (value.resumeSession !== undefined && (typeof value.resumeSession !== "string" || /[\r\n]/u.test(value.resumeSession))) throw new ClientError("Invalid isolated runtime preflight")
+  return {
+    profile: value.profile,
+    repositoryRoot: value.repositoryRoot,
+    cwd: value.cwd,
+    providerArguments: value.providerArguments,
+    ...(value.resumeSession === undefined ? {} : {resumeSession: value.resumeSession})
+  }
+}
+
+export function parseRun(value) {
+  if (!isRecord(value) || typeof value.preflightId !== "string" || typeof value.prompt !== "string" || value.prompt.trim().length === 0 || !Array.isArray(value.providerArguments) || !value.providerArguments.every((item) => typeof item === "string")) {
+    throw new ClientError("Invalid isolated runtime run")
+  }
+  if (!bounded(value.preflightId, 64) || !bounded(value.prompt, 524_288)
+    || value.providerArguments.length > 16 || value.providerArguments.some((item) => !bounded(item, 512))
+    || (value.resumeSession !== undefined && !bounded(value.resumeSession, 256))) {
+    throw new ClientError("Invalid isolated runtime run")
+  }
+  try {
+    validateRelayWriteProviderArguments(value.providerArguments)
+  } catch (error) {
+    throw new ClientError(error instanceof Error ? error.message : "Provider argument is unavailable in relay write mode")
+  }
+  if (value.resumeSession !== undefined && (typeof value.resumeSession !== "string" || /[\r\n]/u.test(value.resumeSession))) throw new ClientError("Invalid isolated runtime run")
+  return {
+    preflightId: value.preflightId,
+    prompt: value.prompt,
+    providerArguments: value.providerArguments,
+    ...(value.resumeSession === undefined ? {} : {resumeSession: value.resumeSession})
+  }
+}
+
+function requestedDeadline(value, maximumMs) {
+  const parsed = Number(value)
+  const maximum = Date.now() + maximumMs
+  return Number.isSafeInteger(parsed) && parsed > Date.now() ? Math.min(parsed, maximum) : maximum
+}
+
+function parseAllowedRoots(value) {
+  let roots
+  try {
+    roots = JSON.parse(safeSetting(value, "THREADWIRE_ALLOWED_WORKTREE_ROOTS"))
+  } catch {
+    throw new Error("THREADWIRE_ALLOWED_WORKTREE_ROOTS must be a JSON array")
+  }
+  if (!Array.isArray(roots) || roots.length === 0 || !roots.every((root) => typeof root === "string" && isAbsolute(root) && normalize(root) === root && root !== "/")) {
+    throw new Error("THREADWIRE_ALLOWED_WORKTREE_ROOTS must contain normalized absolute paths")
+  }
+  return roots
+}
+
+function within(root, child) {
+  const path = relative(root, child)
+  return path === "" || (!path.startsWith("..") && !isAbsolute(path))
+}
+
+function ancestry(root, child) {
+  const remainder = relative(root, child)
+  const paths = [root]
+  let current = root
+  if (remainder === "") return paths
+  for (const component of remainder.split("/")) {
+    current = `${current}/${component}`
+    paths.push(current)
+  }
+  return paths
+}
+
+function taskIdentity(preflight) {
+  return `${preflight.profile}\0${preflight.repositoryRoot}`
+}
+
+function brokerNetworkAddress(value, containerName) {
+  if (!isRecord(value) || !isRecord(value.Containers)) throw new Error("Broker network identity unavailable")
+  for (const [id, endpoint] of Object.entries(value.Containers)) {
+    if (!isRecord(endpoint)) continue
+    if (id === containerName || endpoint.Name === containerName) {
+      const address = endpoint.IPv4Address
+      if (typeof address !== "string" || !/^(?:\d{1,3}\.){3}\d{1,3}\/\d{1,2}$/u.test(address)) break
+      return address.split("/")[0]
+    }
+  }
+  throw new Error("Broker network identity unavailable")
+}
+
+async function readJson(request, capacity, signal) {
+  const chunks = []
+  let bytes = 0
+  for await (const chunk of request) {
+    if (signal?.aborted) throw signal.reason
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+    bytes += buffer.length
+    if (bytes > capacity) throw new ClientError("Request exceeded capacity")
+    chunks.push(buffer)
+  }
+  if (signal?.aborted) throw signal.reason
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"))
+  } catch {
+    throw new ClientError("Invalid request")
+  }
+}
+
+function requireControl(value, expected) {
+  if (value !== `Bearer ${expected}`) throw new ClientError("Request denied")
+}
+
+function normalizedHttpUrl(value, name) {
+  const url = new URL(safeSetting(value, name))
+  if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.search || url.hash) throw new Error(`${name} is invalid`)
+  return url
+}
+
+function safeSetting(value, name) {
+  if (typeof value !== "string" || value.length === 0 || /[\r\n]/u.test(value)) throw new Error(`${name} is required`)
+  return value
+}
+
+function portValue(value, fallback) {
+  if (value === undefined) return fallback
+  const number = Number(value)
+  if (!/^\d+$/u.test(value) || !Number.isSafeInteger(number) || number < 1 || number > 65535) throw new Error("Invalid isolated runtime port")
+  return number
+}
+
+function positiveDuration(value, fallback) {
+  if (value === undefined) return fallback
+  const number = Number(value)
+  if (!/^\d+$/u.test(value) || !Number.isSafeInteger(number) || number < 1 || number > 604_800_000) throw new Error("Invalid session TTL")
+  return number
+}
+
+function positiveInteger(value, fallback) {
+  if (value === undefined) return fallback
+  const number = Number(value)
+  if (!/^\d+$/u.test(value) || !Number.isSafeInteger(number) || number < 1 || number > 1024) throw new Error("Invalid isolated runtime capacity")
+  return number
+}
+
+function parseAllowedModels(value) {
+  let models
+  try {
+    models = JSON.parse(safeSetting(value, "THREADWIRE_ALLOWED_CODEX_MODELS"))
+  } catch {
+    throw new Error("THREADWIRE_ALLOWED_CODEX_MODELS must be a JSON array")
+  }
+  if (!Array.isArray(models) || models.length === 0 || !models.every((model) => typeof model === "string" && /^[A-Za-z0-9._-]{1,128}$/u.test(model))) {
+    throw new Error("THREADWIRE_ALLOWED_CODEX_MODELS must contain model identifiers")
+  }
+  return new Set(models)
+}
+
+function sendJson(response, status, value) {
+  response.writeHead(status, {"content-type": "application/json"})
+  response.end(JSON.stringify(value))
+}
+
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function abortable(promise, signal) {
+  if (signal.aborted) return Promise.reject(signal.reason)
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(signal.reason instanceof Error ? signal.reason : new Error("Isolated runtime operation aborted"))
+    signal.addEventListener("abort", abort, {once: true})
+    promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort))
+  })
+}
+
+function listen(server, port, host) {
+  return new Promise((resolve, reject) => {
+    server.once("error", reject)
+    server.listen(port, host, () => {
+      server.removeListener("error", reject)
+      resolve(undefined)
+    })
+  })
+}
+
+class ClientError extends Error {}
+
+function bounded(value, maximum) {
+  return typeof value === "string" && value.length > 0 && value.length <= maximum && !/[\0\r\n]/u.test(value)
+}
+
+export class PreflightStore {
+  constructor({now = Date.now, ttlMs = PREFLIGHT_TTL_MS, capacity = PREFLIGHT_CAPACITY, taskCapacity = PREFLIGHT_TASK_CAPACITY} = {}) {
+    this.now = now
+    this.ttlMs = ttlMs
+    this.capacity = capacity
+    this.taskCapacity = taskCapacity
+    this.entries = new Map()
+    this.timer = setInterval(() => this.sweep(), Math.max(10, Math.min(ttlMs, 1000)))
+    this.timer.unref()
+  }
+  sweep() {
+    const current = this.now()
+    for (const [id, entry] of this.entries) if (entry.expiresAt <= current) this.entries.delete(id)
+  }
+  add(id, task, value) {
+    this.sweep()
+    this.assertCapacity(task)
+    this.entries.set(id, {task, expiresAt: this.now() + this.ttlMs, value})
+  }
+  assertCapacity(task) {
+    this.sweep()
+    let taskCount = 0
+    for (const entry of this.entries.values()) if (entry.task === task) taskCount++
+    if (this.entries.size >= this.capacity || taskCount >= this.taskCapacity) throw new ClientError("Isolated runtime preflight capacity exhausted")
+  }
+  consume(id) {
+    this.sweep()
+    const entry = this.entries.get(id)
+    this.entries.delete(id)
+    return entry?.value
+  }
+  get size() { return this.entries.size }
+  close() {
+    clearInterval(this.timer)
+    this.entries.clear()
+  }
+}
+
+export class LineageReservations {
+  constructor() {
+    this.active = new Set()
+    this.collecting = false
+  }
+  acquire(lineage) {
+    if (this.active.has(lineage)) throw new ClientError("Codex resume state is already active")
+    this.active.add(lineage)
+    let released = false
+    return () => {
+      if (released) return
+      released = true
+      this.active.delete(lineage)
+    }
+  }
+  beginCollection() {
+    if (this.collecting) throw new Error("Codex state collection overlap")
+    this.collecting = true
+    return () => { this.collecting = false }
+  }
+  values() { return this.active.values() }
+  has(lineage) { return this.active.has(lineage) }
+}
+
+export class ActiveRunAdmission {
+  constructor({capacity = ACTIVE_RUN_CAPACITY, taskCapacity = ACTIVE_TASK_CAPACITY} = {}) {
+    this.capacity = capacity
+    this.taskCapacity = taskCapacity
+    this.active = new Map()
+  }
+  acquire(task) {
+    const taskCount = this.active.get(task) ?? 0
+    let total = 0
+    for (const count of this.active.values()) total += count
+    if (total >= this.capacity || taskCount >= this.taskCapacity) throw new ClientError("Isolated runtime active-run capacity exhausted")
+    this.active.set(task, taskCount + 1)
+    let released = false
+    return () => {
+      if (released) return
+      released = true
+      const remaining = (this.active.get(task) ?? 1) - 1
+      if (remaining === 0) this.active.delete(task)
+      else this.active.set(task, remaining)
+    }
+  }
+}
+
+export class OperationDeadline extends AbsoluteDeadline {
+  constructor(timeoutMs, request, response, now = Date.now) {
+    super(now() + timeoutMs, {request, response, now, timeoutMessage: "Isolated runtime operation timed out", disconnectMessage: "Isolated runtime caller disconnected"})
+  }
+}
+
+function boundedClose(server, timeoutMs) {
+  return Promise.race([
+    new Promise((resolve) => server.close(() => resolve(undefined))),
+    new Promise((resolve) => {
+      const timer = setTimeout(resolve, timeoutMs)
+      timer.unref()
+    })
+  ])
+}
+
+export async function reconcileDockerResources(docker, brokerContainer, stateRegistry, inProcessLineages = new Set(), requestOptions) {
+  const namespace = stateRegistry.namespace
+  const activeLineages = new Set(inProcessLineages)
+  const activeRuns = new Set()
+  const ownedIdentities = new Map(stateRegistry.runRecords().map((identity) => [identity.run, identity]))
+  const cleanupFailed = new Set()
+  const containers = await docker.listContainers({"org.threadwire.owner": "isolated-runtime"}, true, requestOptions)
+  for (const container of Array.isArray(containers) ? containers : []) {
+    const labels = validResourceLabels(container?.Labels, namespace, true)
+    if (!labels) continue
+    const persisted = ownedIdentities.get(labels.run)
+    if (!persisted || stateRegistry.sealRun(persisted) !== labels.seal) continue
+    const inspection = await docker.inspectContainer(container.Id, requestOptions).catch(() => undefined)
+    const identity = ownedContainerIdentity(inspection, labels)
+    if (!identity || !stateRegistry.ownsRun(identity, labels.seal)) {
+      cleanupFailed.add(labels.run)
+      continue
+    }
+    if (inProcessLineages.has(labels.lineage)) {
+      activeLineages.add(labels.lineage)
+      activeRuns.add(labels.run)
+      continue
+    }
+    if (inProcessLineages.has(labels.lineage)) {
+      activeLineages.add(labels.lineage)
+      activeRuns.add(labels.run)
+      continue
+    }
+    await docker.removeContainer(container.Id, requestOptions).catch(() => cleanupFailed.add(labels.run))
+  }
+  const networks = await docker.listNetworks({"org.threadwire.owner": "isolated-runtime"}, requestOptions)
+  for (const network of Array.isArray(networks) ? networks : []) {
+    const labels = validResourceLabels(network?.Labels, namespace, false)
+    if (!labels || activeRuns.has(labels.run) || cleanupFailed.has(labels.run)) continue
+    const identity = ownedIdentities.get(labels.run)
+    if (!identity || stateRegistry.sealRun(identity) !== labels.seal) continue
+    const inspection = await docker.inspectNetwork(network.Id, requestOptions).catch(() => undefined)
+    if (!identity || !ownedNetworkIdentity(inspection, labels, identity, brokerContainer)
+      || !stateRegistry.ownsRun(identity, labels.seal)) {
+      cleanupFailed.add(labels.run)
+      continue
+    }
+    if (inProcessLineages.has(labels.lineage)) {
+      activeLineages.add(labels.lineage)
+      activeRuns.add(labels.run)
+      continue
+    }
+    const brokerEndpoint = Object.entries(inspection.Containers ?? {}).find(([, endpoint]) => endpoint?.Name === brokerContainer)
+    if (brokerEndpoint) await docker.disconnectNetwork(network.Id, brokerContainer, requestOptions).catch(() => {})
+    await docker.removeNetwork(network.Id, requestOptions).catch(() => cleanupFailed.add(labels.run))
+  }
+  for (const identity of ownedIdentities.values()) {
+    if (activeRuns.has(identity.run) || cleanupFailed.has(identity.run)) {
+      activeLineages.add(identity.lineage)
+      continue
+    }
+    if (inProcessLineages.has(identity.lineage)) {
+      activeLineages.add(identity.lineage)
+      continue
+    }
+    await stateRegistry.completeRun(identity.run, requestOptions?.signal).catch(() => activeLineages.add(identity.lineage))
+  }
+  return [...activeLineages]
+}
+
+function validResourceLabels(value, namespace, container) {
+  if (!isRecord(value)) return undefined
+  const expectedKeys = [
+    "org.threadwire.owner", "org.threadwire.namespace", "org.threadwire.run",
+    "org.threadwire.lineage", "org.threadwire.task", "org.threadwire.state-volume",
+    "org.threadwire.run-seal",
+    ...(container ? ["org.threadwire.network"] : [])
+  ]
+  if (Object.keys(value).length !== expectedKeys.length || expectedKeys.some((key) => typeof value[key] !== "string")) return undefined
+  const run = value["org.threadwire.run"]
+  const lineage = value["org.threadwire.lineage"]
+  const volume = value["org.threadwire.state-volume"]
+  const seal = value["org.threadwire.run-seal"]
+  if (value["org.threadwire.owner"] !== "isolated-runtime" || value["org.threadwire.namespace"] !== namespace
+    || !/^tw-[0-9a-f]{24}$/u.test(run) || !/^[0-9a-f]{48}$/u.test(lineage)
+    || !/^[0-9a-f]{64}$/u.test(value["org.threadwire.task"])
+    || !/^[0-9a-f]{64}$/u.test(seal)
+    || volume !== `threadwire-state-${namespace}-${lineage}`
+    || (container && value["org.threadwire.network"] !== `${run}-net`)) return undefined
+  return {run, lineage, volume, seal, task: value["org.threadwire.task"], namespace}
+}
+
+function ownedContainerIdentity(container, labels) {
+  if (!isRecord(container) || container.Name !== `/${labels.run}-worker`
+    || !isRecord(container.Config) || !isRecord(container.HostConfig)
+    || container.Config.Image !== container.Image || !isDigestImage(container.Config.Image)
+    || JSON.stringify(container.Config.Entrypoint) !== JSON.stringify(["/usr/local/libexec/threadwire/worker-entrypoint"])
+    || ![null, undefined].includes(container.Config.Cmd) || container.Config.User !== "10002:10002"
+    || typeof container.Config.WorkingDir !== "string" || !within("/worktree", container.Config.WorkingDir)
+    || container.HostConfig.NetworkMode !== `${labels.run}-net`
+    || !validWorkerSecurity(container.Config, container.HostConfig)
+    || !Array.isArray(container.HostConfig.Mounts) || container.HostConfig.Mounts.length !== 2) return undefined
+  const inspectedLabels = validResourceLabels(container.Config.Labels, labels.namespace, true)
+  if (!inspectedLabels || JSON.stringify(inspectedLabels) !== JSON.stringify(labels)) return undefined
+  const state = container.HostConfig.Mounts.find((mount) => mount?.Target === "/home/worker")
+  const worktree = container.HostConfig.Mounts.find((mount) => mount?.Target === "/worktree")
+  if (state?.Type !== "volume" || state.Source !== labels.volume || state.ReadOnly === true
+    || Object.keys(state).some((key) => !["Type", "Source", "Target", "ReadOnly"].includes(key))) return undefined
+  if (!validWorktreeMount(worktree)) return undefined
+  return runIdentityFrom(labels, container.Config.Image, worktree)
+}
+
+function validWorkerSecurity(config, host) {
+  if (host.AutoRemove !== false || host.ReadonlyRootfs !== true
+    || host.Privileged === true || JSON.stringify(host.CapDrop) !== JSON.stringify(["ALL"])
+    || JSON.stringify(host.CapAdd ?? null) !== "null"
+    || JSON.stringify(host.SecurityOpt) !== JSON.stringify(["no-new-privileges"])
+    || host.PidsLimit !== 128 || host.Memory !== 1_073_741_824 || host.NanoCpus !== 2_000_000_000
+    || !isRecord(host.Tmpfs) || Object.keys(host.Tmpfs).length !== 2
+    || host.Tmpfs["/tmp"] !== "rw,noexec,nosuid,nodev,size=67108864,uid=10002,gid=10002"
+    || host.Tmpfs["/run"] !== "rw,noexec,nosuid,nodev,size=1048576,uid=10002,gid=10002"
+    || !Array.isArray(host.Ulimits) || host.Ulimits.length !== 3
+    || ![
+      ["nofile", 1024, 1024], ["core", 0, 0], ["fsize", 1_073_741_824, 1_073_741_824]
+    ].every(([name, soft, hard], index) => host.Ulimits[index]?.Name === name
+      && host.Ulimits[index]?.Soft === soft && host.Ulimits[index]?.Hard === hard)) return false
+  const forbidden = {
+    Binds: [null, []], Devices: [null, []], DeviceRequests: [null, []], PortBindings: [null, {}],
+    Links: [null, []], ExtraHosts: [null, []], VolumesFrom: [null, []], Dns: [null, []],
+    DnsSearch: [null, []], Sysctls: [null, {}]
+  }
+  for (const [key, defaults] of Object.entries(forbidden)) {
+    if (!defaults.some((value) => JSON.stringify(host[key] ?? null) === JSON.stringify(value))) return false
+  }
+  if (![undefined, "", "private"].includes(host.PidMode) || ![undefined, "", "private"].includes(host.IpcMode)
+    || ![undefined, ""].includes(host.UTSMode) || ![undefined, ""].includes(host.UsernsMode)
+    || ![undefined, "", "private"].includes(host.CgroupnsMode) || host.PublishAllPorts === true) return false
+  if (!Array.isArray(config.Env) || config.Env.length !== 13 + (config.Env.some((entry) => entry.startsWith("THREADWIRE_RESUME_SESSION=")) ? 1 : 0)) return false
+  const names = config.Env.map((entry) => entry.split("=", 1)[0])
+  const expected = [
+    "HOME", "CODEX_HOME", "TMPDIR", "OPENAI_BASE_URL", "OPENAI_API_KEY", "CODEX_API_KEY",
+    "THREADWIRE_PROMPT", "THREADWIRE_CODEX_ARGUMENTS", "THREADWIRE_WORKTREE_INODE", "THREADWIRE_CWD_INODE"
+  ]
+  return expected.every((name) => names.filter((entry) => entry === name).length === 1)
+    && config.Env.includes("PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin")
+    && config.Env.includes("NODE_VERSION=22.17.0") && config.Env.includes("YARN_VERSION=1.22.22")
+}
+
+function ownedNetworkIdentity(network, labels, identity, brokerContainer) {
+  if (!isRecord(network) || network.Name !== `${labels.run}-net` || network.Internal !== true
+    || network.Driver !== "bridge" || network.Scope !== "local"
+    || network.EnableIPv6 !== false || network.Attachable !== false || network.Ingress !== false
+    || network.ConfigOnly !== false || !isRecord(network.Options) || Object.keys(network.Options).length !== 0
+    || !isRecord(network.Containers)) return undefined
+  const inspectedLabels = validResourceLabels(network.Labels, labels.namespace, false)
+  if (!inspectedLabels || JSON.stringify(inspectedLabels) !== JSON.stringify(labels)) return undefined
+  const endpoints = Object.values(network.Containers)
+  if (endpoints.some((endpoint) => !isRecord(endpoint)
+    || ![identity.container, brokerContainer].includes(endpoint.Name))) return undefined
+  return true
+}
+
+function validWorktreeMount(mount) {
+  if (!isRecord(mount) || mount.Target !== "/worktree" || mount.ReadOnly === true) return false
+  if (mount.Type === "bind") {
+    return Object.keys(mount).every((key) => ["Type", "Source", "Target", "ReadOnly", "BindOptions"].includes(key))
+      && typeof mount.Source === "string" && isAbsolute(mount.Source)
+      && isRecord(mount.BindOptions) && Object.keys(mount.BindOptions).length === 1
+      && mount.BindOptions.Propagation === "rprivate"
+  }
+  return mount.Type === "volume" && typeof mount.Source === "string"
+    && Object.keys(mount).every((key) => ["Type", "Source", "Target", "ReadOnly", "VolumeOptions"].includes(key))
+    && isRecord(mount.VolumeOptions) && Object.keys(mount.VolumeOptions).length === 1
+    && typeof mount.VolumeOptions.Subpath === "string" && mount.VolumeOptions.Subpath.length > 0
+}
+
+function runIdentityFrom(labels, image, worktree) {
+  return {
+    namespace: labels.namespace, run: labels.run, lineage: labels.lineage, task: labels.task,
+    volume: labels.volume, network: `${labels.run}-net`, container: `${labels.run}-worker`,
+    image, worktreeType: worktree.Type, worktreeSource: worktree.Source,
+    worktreeSubpath: worktree.Type === "volume" ? worktree.VolumeOptions.Subpath : ""
+  }
+}
+
+function expectedRunIdentity(options, run, network, state, worktreeSubpath) {
+  const volumeMode = options.worktreeVolume !== undefined
+  return {
+    namespace: options.stateRegistry.namespace, run, lineage: state.lineage,
+    task: state.labels["org.threadwire.task"], volume: state.volume, network,
+    container: `${run}-worker`, image: options.workerImage,
+    worktreeType: volumeMode ? "volume" : "bind",
+    worktreeSource: volumeMode ? options.worktreeVolume : options.preflight.repositoryRoot,
+    worktreeSubpath: volumeMode ? worktreeSubpath : ""
+  }
+}
+
+export function deriveVolumeWorktreeSubpath(worktreeRoot, repositoryRoot) {
+  if (typeof worktreeRoot !== "string" || typeof repositoryRoot !== "string" || !within(worktreeRoot, repositoryRoot)) {
+    throw new ClientError("Configured worktree has an invalid volume subpath")
+  }
+  const subpath = relative(worktreeRoot, repositoryRoot)
+  if (subpath === "" || isAbsolute(subpath) || normalize(subpath) !== subpath || subpath.split("/").includes("..")) {
+    throw new ClientError("Configured worktree has an invalid volume subpath")
+  }
+  return subpath
+}