threadwire 0.1.25 → 0.1.27

package/src/isolated-runtime.js

@@ -5,9 +5,10 @@ import {randomBytes} from "node:crypto"
 import {once} from "node:events"
 import {lstat, realpath} from "node:fs/promises"
 import {createServer} from "node:http"
+import {hostname} from "node:os"
 import {isAbsolute, join, normalize, relative} from "node:path"
 import {DockerApi, DockerApiError} from "./docker-api.js"
-import {buildKimiBindingValidatorSpec, buildKimiRelayContainerSpec, buildWorkerContainerSpec, isDigestImage} from "./isolated-worker.js"
+import {buildGitMetadataSnapshotSpec, buildKimiBindingValidatorSpec, buildKimiRelayContainerSpec, buildKimiSourceSnapshotSpec, buildWorkerContainerSpec, isDigestImage} from "./isolated-worker.js"
 import {validateRelayWriteProviderArguments} from "./relay-write.js"
 import {codexSessionId, parseCodexEvent} from "./providers/codex.js"
 import {kimiSessionEnvelopeId, validateKimiProviderArguments} from "./providers/kimi.js"
@@ -15,7 +16,10 @@ import {parseApprovedKimiModels} from "./kimi-model-broker-policy.js"
 import {parseThreadwireBinding, resumeTaskIdentity, threadwireBindingDigest} from "./threadwire-binding.js"
 import {openStateRegistry, validateStateVolume} from "./isolated-state.js"
 import {assertNoNestedMounts} from "./mount-policy.js"
-import {AbsoluteDeadline, deadlineAfter} from "./absolute-deadline.js"
+import {MUTATION_CAPABILITIES, parseMutationPolicy} from "./mutation-policy.js"
+import {gitSnapshot, snapshotMutations, reconcileMutationResult} from "./mutation-snapshot.js"
+import {AbsoluteDeadline, abortable, deadlineAfter} from "./absolute-deadline.js"
+import {exactKeys, isRecord} from "./record-helpers.js"
 
 const MAX_PREFLIGHT_BYTES = 32_768
 const MAX_RUN_BYTES = 1_048_576
@@ -128,7 +132,8 @@ export async function startIsolatedRuntime(options = {}) {
       }
       if (request.method === "POST" && request.url === "/preflight") {
         const releaseIncoming = incomingRequests.acquire("preflight")
-        const launchDeadlineAt = requestedDeadline(request.headers["x-threadwire-launch-deadline"], workerTimeoutMs)
+        const launchDeadlineHeader = request.headers["x-threadwire-launch-deadline"]
+        const launchDeadlineAt = requestedDeadline(launchDeadlineHeader, workerTimeoutMs)
         const operation = new AbsoluteDeadline(minimumDeadline(Date.now() + preflightTimeoutMs, launchDeadlineAt), {
           signal: shutdown.signal, request, response, timeoutMessage: "Isolated runtime operation timed out", disconnectMessage: "Isolated runtime caller disconnected"
         })
@@ -149,8 +154,11 @@ export async function startIsolatedRuntime(options = {}) {
             try { validateStateVolume(volume, state.volume, state.labels) } catch { throw new ClientError(`${providerName(provider)} resume state is unavailable`) }
           } else state = stateRegistry.allocate(task)
           const preflightId = randomBytes(24).toString("base64url")
-          preflights.add(preflightId, task, {...selection, provider, providerSelection, state, fingerprint, worktreeRoot, ...(launchDeadlineAt === undefined ? {} : {launchDeadlineAt})})
-          sendJson(response, 200, {ok: true, preflightId, ...(launchDeadlineAt === undefined ? {} : {launchDeadlineAt})})
+          // Only an explicitly requested launch deadline is carried into the run;
+          // the workerTimeoutMs fallback caps only the preflight operation itself.
+          const explicitLaunchDeadline = launchDeadlineHeader === undefined ? undefined : launchDeadlineAt
+          preflights.add(preflightId, task, {...selection, provider, providerSelection, state, fingerprint, worktreeRoot, ...(explicitLaunchDeadline === undefined ? {} : {launchDeadlineAt: explicitLaunchDeadline})})
+          sendJson(response, 200, {ok: true, preflightId, ...(explicitLaunchDeadline === undefined ? {} : {launchDeadlineAt: explicitLaunchDeadline})})
         } finally {
           operation.close()
           releaseIncoming()
@@ -178,8 +186,13 @@ export async function startIsolatedRuntime(options = {}) {
         const operationSignal = runLifecycle === undefined
           ? shutdown.signal
           : AbortSignal.any([shutdown.signal, runLifecycle.signal])
-        const operation = new AbsoluteDeadline(minimumDeadline(preflight.launchDeadlineAt,
-          requestedDeadline(request.headers["x-threadwire-launch-deadline"], workerTimeoutMs)), {
+        const runHeaderDeadline = request.headers["x-threadwire-launch-deadline"] === undefined
+          ? undefined
+          : requestedDeadline(request.headers["x-threadwire-launch-deadline"], workerTimeoutMs)
+        const launchDeadlineAt = preflight.launchDeadlineAt === undefined
+          ? runHeaderDeadline
+          : (runHeaderDeadline === undefined ? preflight.launchDeadlineAt : Math.min(preflight.launchDeadlineAt, runHeaderDeadline))
+        const operation = new AbsoluteDeadline(launchDeadlineAt, {
           signal: operationSignal, request, response, timeoutMessage: "Isolated runtime launch timed out", disconnectMessage: "Isolated runtime caller disconnected",
           destroyRequestOnAbort: runLifecycle === undefined
         })
@@ -264,7 +277,7 @@ async function verifyPrerequisites(options) {
   if (typeof image.Id !== "string" || !isDigestImage(image.Id)) throw new Error("Worker image unavailable")
   const validatedWorktree = selection.provider === "kimi"
     ? await verifyKimiBindingAdmission(docker, selection.binding, operation.options())
-    : await validateWorktreeSelection(selection.repositoryRoot, selection.cwd, allowedRoots)
+    : await validateWorktreeSelection(selection.repositoryRoot, selection.cwd, allowedRoots, selection.mutationPolicy)
   const health = await abortable(fetchImplementation(new URL("/healthz", brokerUrl), {
     method: "GET",
     redirect: "error",
@@ -320,11 +333,11 @@ async function verifyKimiBindingAdmission(docker, value, requestOptions) {
   return {fingerprint: [], root: binding.source.target}
 }
 
-export async function validateWorktree(repositoryRoot, cwd, allowedRoots) {
-  return (await validateWorktreeSelection(repositoryRoot, cwd, allowedRoots)).fingerprint
+export async function validateWorktree(repositoryRoot, cwd, allowedRoots, mutationPolicy) {
+  return (await validateWorktreeSelection(repositoryRoot, cwd, allowedRoots, mutationPolicy)).fingerprint
 }
 
-export async function validateWorktreeSelection(repositoryRoot, cwd, allowedRoots) {
+export async function validateWorktreeSelection(repositoryRoot, cwd, allowedRoots, mutationPolicy) {
   const root = allowedRoots
     .filter((allowed) => within(allowed, repositoryRoot))
     .sort((first, second) => second.length - first.length)[0]
@@ -347,8 +360,16 @@ export async function validateWorktreeSelection(repositoryRoot, cwd, allowedRoot
   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")
+    if (gitEntry.isDirectory()) {
+      // An explicit mutation policy is what authorizes a .git directory to
+      // enter the worker; the per-run policy is then enforced at container
+      // creation time (read-only worktree/.git mounts when denied). Without a
+      // policy the historical behavior is preserved: common Git directories are
+      // rejected to avoid leaking repository metadata into an unbounded run.
+      if (mutationPolicy === undefined) throw new ClientError("Common Git directories cannot enter the worker")
+    } else 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
@@ -382,6 +403,8 @@ export async function runIsolatedWorker(options) {
   let relayId
   let relayContainerName
   let containerId
+  let gitSnapshotContainerId
+  let gitMetadataVolumeName = undefined
   let grantToken
   let grantRenewalTimer
   let runTracked = false
@@ -509,6 +532,41 @@ export async function runIsolatedWorker(options) {
     const worktreeMetadata = provider === "kimi" ? {ino: "0"} : repository.find((entry) => entry.path === options.preflight.repositoryRoot)
     const cwdMetadata = provider === "kimi" ? {ino: "0"} : repository.find((entry) => entry.path === options.preflight.cwd)
     if (worktreeMetadata === undefined || cwdMetadata === undefined) throw new Error("Worktree fingerprint unavailable")
+    const mutationPolicy = options.preflight.mutationPolicy
+    const useGitMetadataVolume = provider === "codex" && options.worktreeVolume !== undefined && mutationPolicy !== undefined
+      && mutationPolicy.worktreeEdit === true && mutationPolicy.commit === false
+    let gitMetadataVolumeName
+    if (useGitMetadataVolume) {
+      runStage = "git-metadata-volume"
+      gitMetadataVolumeName = `${runId}-git`
+      await options.docker.createVolume(gitMetadataVolumeName, {...resourceLabels, "org.threadwire.role": "git-metadata-snapshot"}, operation.options())
+      runStage = "git-metadata-snapshot"
+      const snapshotImage = await resolveRuntimeImage(options.docker, operation)
+      const snapshotSpec = buildGitMetadataSnapshotSpec({
+        image: snapshotImage,
+        sourceVolume: options.worktreeVolume,
+        sourceSubpath: worktreeSubpath,
+        targetVolume: gitMetadataVolumeName,
+        name: `${runId}-git-snapshot`,
+        labels: resourceLabels
+      })
+      const snapshotContainer = /** @type {{Id?: unknown}} */ (await options.docker.createContainer(`${runId}-git-snapshot`, snapshotSpec, operation.options()))
+      if (typeof snapshotContainer.Id !== "string") throw new Error("Git metadata snapshot helper creation failed")
+      gitSnapshotContainerId = snapshotContainer.Id
+      try {
+        await validateWorkerMountInventory(await options.docker.inspectContainer(gitSnapshotContainerId, operation.options()), snapshotSpec.HostConfig.Mounts)
+        await options.docker.startContainer(gitSnapshotContainerId, operation.options())
+        const snapshotWait = /** @type {{StatusCode?: unknown}} */ (await options.docker.waitContainer(gitSnapshotContainerId, operation.options()))
+        if (snapshotWait.StatusCode !== 0) {
+          const statusCode = Number(snapshotWait.StatusCode)
+          const category = statusCode === 1 ? "helper-logic" : statusCode === 2 ? "helper-runtime" : "helper-unknown"
+          process.stderr.write(`threadwire-runtime: git metadata snapshot helper exited ${statusCode} (${category})\n`)
+          throw new Error(`Git metadata snapshot helper failed (${category})`)
+        }
+      } finally {
+        await cleanupDocker(() => options.docker.removeContainer(gitSnapshotContainerId, operation.options())).catch(() => {})
+      }
+    }
     const spec = buildWorkerContainerSpec({
       provider,
       image: options.workerImage,
@@ -536,7 +594,9 @@ export async function runIsolatedWorker(options) {
             subpath: worktreeSubpath
           }
         }),
-      ...(options.resumeSession === undefined ? {} : {resumeSession: options.resumeSession})
+      ...(gitMetadataVolumeName === undefined ? {} : {gitOverlayVolume: {name: gitMetadataVolumeName}}),
+      ...(options.resumeSession === undefined ? {} : {resumeSession: options.resumeSession}),
+      ...(options.preflight.mutationPolicy === undefined ? {} : {mutationPolicy: options.preflight.mutationPolicy})
     })
     runStage = "worker-create"
     const container = /** @type {{Id?: unknown}} */ (await options.docker.createContainer(`${runId}-worker`, spec, operation.options()))
@@ -553,6 +613,23 @@ export async function runIsolatedWorker(options) {
         headers: {authorization: `Bearer ${options.brokerAdminToken}`}
       }), operation.signal)
     if (!activationResponse.ok) throw new Error("Model broker grant activation failed")
+    runStage = "snapshot-before"
+    const snapshotRepository = provider === "codex" ? options.preflight.repositoryRoot : undefined
+    const beforeSnapshot = mutationPolicy !== undefined
+      ? await captureMutationSnapshot({
+        provider,
+        docker: options.docker,
+        repositoryRoot: snapshotRepository,
+        binding: options.preflight.binding,
+        workerImage: options.workerImage,
+        runId,
+        namespace: options.stateRegistry.namespace,
+        lineage: state.lineage,
+        taskHash: state.labels["org.threadwire.task"],
+        when: "before",
+        operation
+      })
+      : undefined
     const leaseMs = grantLease(options.grantLeaseMs)
     let renewing = false
     let renewalConfirmed = false
@@ -611,11 +688,13 @@ export async function runIsolatedWorker(options) {
       rawChunks = provider === "kimi" ? [] : chunks.map((chunk) => ({channel: chunk.channel, data: chunk.data.toString("base64")}))
       if (provider === "kimi") for (const record of records) await publishRecord?.(record)
     }
-    const result = {
+    let result = {
       exitCode: typeof wait.StatusCode === "number" ? wait.StatusCode : 1,
       records,
       rawChunks
     }
+    const mutationClaimResult = extractMutationClaim(result.records)
+    result.records = mutationClaimResult.records
     let sessionIds = [...new Set(result.records.filter((record) => record.type === "session").map((record) => record.sessionId))]
     if (provider === "kimi" && result.exitCode !== 0) {
       result.records = result.records.filter((record) => record.type !== "session")
@@ -628,6 +707,42 @@ export async function runIsolatedWorker(options) {
         throw new Error("Kimi worker did not preserve the exact resume session")
       }
     }
+    if (beforeSnapshot !== undefined) {
+      runStage = "snapshot-after"
+      const afterSnapshot = await captureMutationSnapshot({
+        provider,
+        docker: options.docker,
+        repositoryRoot: snapshotRepository,
+        binding: options.preflight.binding,
+        workerImage: options.workerImage,
+        runId,
+        namespace: options.stateRegistry.namespace,
+        lineage: state.lineage,
+        taskHash: state.labels["org.threadwire.task"],
+        when: "after",
+        operation
+      })
+      const observed = snapshotMutations(beforeSnapshot, afterSnapshot)
+      const reconciliation = reconcileMutationResult({
+        policy: /** @type {import("./mutation-policy.js").MutationPolicy} */ (mutationPolicy),
+        observed,
+        providerExitCode: result.exitCode,
+        providerClaim: mutationClaimResult.claim
+      })
+      result = {
+        ...result,
+        exitCode: reconciliation.exitCode,
+        observedMutations: reconciliation.observedMutations
+      }
+      if (reconciliation.blocker !== undefined) {
+        result.mutationBlocker = reconciliation.blocker
+      }
+      if (provider === "kimi" && result.exitCode !== 0) {
+        result.records = result.records.filter((record) => record.type !== "session")
+        sessionIds = []
+        deferredSessions.length = 0
+      }
+    }
     if (freshState && result.exitCode === 0) {
       if (sessionIds.length === 0) throw new Error(`${providerName(provider)} session state was not established`)
       await options.stateRegistry.register(sessionIds, state, options.sessionTtlMs, operation.signal)
@@ -654,9 +769,17 @@ export async function runIsolatedWorker(options) {
         throw error
       }
     }
+    if (result.observedMutations !== undefined) {
+      await options.onRecord?.({
+        type: "observed_mutations",
+        mutations: result.observedMutations,
+        ...(result.mutationBlocker === undefined ? {} : {blocker: result.mutationBlocker})
+      })
+    }
     workerResult = result
   } catch (error) {
-    process.stderr.write(`threadwire-runtime: isolated run failed at ${runStage}\n`)
+    const message = error instanceof Error ? error.message : "unknown"
+    process.stderr.write(`threadwire-runtime: isolated run failed at ${runStage}: ${message}\n`)
     runError = error
   } finally {
     let resourcesRemoved = true
@@ -668,7 +791,11 @@ export async function runIsolatedWorker(options) {
       ? deadlineAfter(5_000, {timeoutMessage: "Isolated runtime emergency cleanup timeout"})
       : undefined
     const cleanupOperation = emergencyCleanup ?? operation
-    const cleanupOptions = () => cleanupOperation.options()
+    const cleanupOptions = cleanupOperation.options()
+    // Caller/deadline aborts cannot authorize further graceful shutdown. Force
+    // an immediate KILL for the worker container so the bounded emergency
+    // cleanup window is not consumed by a TERM grace period.
+    const workerCleanupOptions = {...cleanupOptions, forceKill: operation.signal.aborted}
     if (grantToken !== undefined) {
       await abortable(options.fetchImplementation(new URL(`/admin/grants/${encodeURIComponent(grantToken)}`, options.brokerUrl), {
         method: "DELETE",
@@ -676,13 +803,13 @@ export async function runIsolatedWorker(options) {
         headers: {authorization: `Bearer ${options.brokerAdminToken}`}
       }), cleanupOperation.signal).catch(() => process.stderr.write("threadwire-isolated-runtime: grant cleanup failed\n"))
     }
-    if (validatorId !== undefined) await cleanupDocker(() => options.docker.removeContainer(validatorId, cleanupOptions())).catch(() => {
+    if (validatorId !== undefined) await cleanupDocker(() => options.docker.removeContainer(validatorId, cleanupOptions)).catch(() => {
       resourcesRemoved = false
       process.stderr.write("threadwire-isolated-runtime: validator cleanup failed\n")
     })
     if (containerId !== undefined) {
       try {
-        await stopAndRemoveWorkerContainer(options.docker, containerId, cleanupOptions())
+        await stopAndRemoveWorkerContainer(options.docker, containerId, workerCleanupOptions)
       } catch (error) {
         resourcesRemoved = false
         cleanupFailure = error instanceof ContainerCleanupConfirmationError
@@ -691,22 +818,26 @@ export async function runIsolatedWorker(options) {
         process.stderr.write("threadwire-isolated-runtime: worker cleanup failed\n")
       }
     }
-    if (relayId !== undefined) await cleanupDocker(() => options.docker.removeContainer(relayId, cleanupOptions())).catch(() => {
+    if (gitMetadataVolumeName !== undefined) await cleanupDocker(() => options.docker.removeVolume(gitMetadataVolumeName, cleanupOptions)).catch(() => {
+      resourcesRemoved = false
+      process.stderr.write("threadwire-isolated-runtime: git metadata volume cleanup failed\n")
+    })
+    if (relayId !== undefined) await cleanupDocker(() => options.docker.removeContainer(relayId, cleanupOptions)).catch(() => {
       resourcesRemoved = false
       process.stderr.write("threadwire-isolated-runtime: relay cleanup failed\n")
     })
     if (networkId !== undefined) {
-      if (provider !== "kimi") await cleanupDocker(() => options.docker.disconnectNetwork(networkId, options.brokerContainer, cleanupOptions())).catch(() => {})
-      await cleanupDocker(() => options.docker.removeNetwork(networkId, cleanupOptions())).catch(() => {
+      if (provider !== "kimi") 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 (egressNetworkId !== undefined) await cleanupDocker(() => options.docker.removeNetwork(egressNetworkId, cleanupOptions())).catch(() => {
+    if (egressNetworkId !== undefined) await cleanupDocker(() => options.docker.removeNetwork(egressNetworkId, cleanupOptions)).catch(() => {
       resourcesRemoved = false
       process.stderr.write("threadwire-isolated-runtime: egress network cleanup failed\n")
     })
-    if (freshState && !keepFreshState && resourcesRemoved) await cleanupDocker(() => options.docker.removeVolume(state.volume, cleanupOptions())).catch(() => { resourcesRemoved = false })
+    if (freshState && !keepFreshState && resourcesRemoved) await cleanupDocker(() => options.docker.removeVolume(state.volume, cleanupOptions)).catch(() => { resourcesRemoved = false })
     if (runTracked && resourcesRemoved) await options.stateRegistry.completeRun(runId, cleanupOperation.signal).catch(() => {})
     emergencyCleanup?.close()
   }
@@ -715,6 +846,89 @@ export async function runIsolatedWorker(options) {
   return workerResult
 }
 
+/**
+ * Capture a credential-free pre/post mutation snapshot for the active provider.
+ * Codex snapshots the host-mounted repository root directly; Kimi snapshots the
+ * named source volume through an offline helper container because the runtime
+ * itself does not mount the task source volume. The helper uses the same
+ * immutable worker image that will run the worker, so it is available on the
+ * task daemon without inspecting the supervisor runtime container.
+ * @param {{provider: "codex" | "kimi", docker: DockerApi, repositoryRoot?: string, binding?: unknown, workerImage?: string, runId: string, namespace: string, lineage: string, taskHash: string, when: "before" | "after", operation: import("./absolute-deadline.js").AbsoluteDeadline}} options
+ */
+export async function captureMutationSnapshot(options) {
+  if (options.provider === "kimi") {
+    if (typeof options.workerImage !== "string" || !isDigestImage(options.workerImage)) throw new Error("Kimi snapshot worker image is invalid")
+    return runKimiSourceSnapshot({
+      docker: options.docker,
+      binding: /** @type {import("./threadwire-binding.js").ThreadwireBinding} */ (options.binding),
+      image: options.workerImage,
+      runId: options.runId,
+      namespace: options.namespace,
+      lineage: options.lineage,
+      taskHash: options.taskHash,
+      when: options.when,
+      operation: options.operation
+    })
+  }
+  return gitSnapshot(/** @type {string} */ (options.repositoryRoot), {timeoutMs: 10_000}).catch((error) => {
+    throw new Error(`Mutation snapshot failed: ${error instanceof Error ? error.message : "unknown"}`)
+  })
+}
+
+/**
+ * Run an offline helper container that snapshots a Kimi source volume. The
+ * helper uses an explicit immutable image available on the task daemon, has no
+ * network, mounts only the source volume read-only, and carries no credentials.
+ * @param {{docker: DockerApi, binding: import("./threadwire-binding.js").ThreadwireBinding, image: string, runId: string, namespace: string, lineage: string, taskHash: string, when: "before" | "after", operation: import("./absolute-deadline.js").AbsoluteDeadline}} options
+ */
+async function runKimiSourceSnapshot(options) {
+  const binding = parseThreadwireBinding(options.binding)
+  const spec = buildKimiSourceSnapshotSpec({
+    image: options.image,
+    sourceVolume: binding.source.volume,
+    sourceTarget: binding.source.target,
+    uid: binding.runtime.uid,
+    gid: binding.runtime.gid,
+    name: `${options.runId}-snapshot-${options.when}`,
+    labels: {
+      "org.threadwire.owner": "isolated-runtime",
+      "org.threadwire.namespace": options.namespace,
+      "org.threadwire.provider": "kimi",
+      "org.threadwire.run": options.runId,
+      "org.threadwire.lineage": options.lineage,
+      "org.threadwire.task": options.taskHash,
+      "org.threadwire.role": "snapshot"
+    }
+  })
+  const created = /** @type {{Id?: unknown}} */ (await options.docker.createContainer(`${options.runId}-snapshot-${options.when}`, spec, options.operation.options()))
+  if (typeof created.Id !== "string") throw new Error("Kimi snapshot helper creation failed")
+  const containerId = created.Id
+  try {
+    await validateWorkerMountInventory(await options.docker.inspectContainer(containerId, options.operation.options()), spec.HostConfig.Mounts)
+    await options.docker.startContainer(containerId, options.operation.options())
+    const wait = /** @type {{StatusCode?: unknown}} */ (await options.docker.waitContainer(containerId, options.operation.options()))
+    if (wait.StatusCode !== 0) throw new Error("Kimi snapshot helper failed")
+    const logs = /** @type {Buffer} */ (await options.docker.logs(containerId, options.operation.options()))
+    const chunks = demultiplexDockerLogChunks(logs)
+    const stdout = Buffer.concat(chunks.filter((chunk) => chunk.channel === "stdout").map((chunk) => chunk.data)).toString("utf8").trim()
+    let parsed
+    try { parsed = JSON.parse(stdout) } catch { throw new Error("Kimi snapshot helper returned invalid JSON") }
+    if (!isRecord(parsed)) throw new Error("Kimi snapshot helper returned non-object")
+    return /** @type {import("./mutation-snapshot.js").GitSnapshot} */ (parsed)
+  } finally {
+    await cleanupDocker(() => options.docker.removeContainer(containerId, options.operation.options())).catch(() => {})
+  }
+}
+
+async function resolveRuntimeImage(docker, operation) {
+  const containerId = hostname()
+  const inspection = await docker.inspectContainer(containerId, operation.options()).catch(() => undefined)
+  if (!isRecord(inspection) || typeof inspection.Image !== "string" || !isDigestImage(inspection.Image)) {
+    throw new Error("Runtime self-image unavailable")
+  }
+  return inspection.Image
+}
+
 async function cleanupDocker(operation) {
   return operation()
 }
@@ -722,23 +936,39 @@ async function cleanupDocker(operation) {
 async function stopAndRemoveWorkerContainer(docker, containerId, requestOptions) {
   let inspection = await docker.inspectContainer(containerId, requestOptions)
   if (typeof inspection?.State?.Running !== "boolean") throw new Error("Worker container state unavailable")
-  if (inspection.State.Running) {
+  if (!inspection.State.Running) {
+    await docker.removeContainer(containerId, requestOptions)
+    return
+  }
+  // A caller/deadline abort bypasses the normal TERM grace to avoid spending
+  // the bounded emergency cleanup budget on a cooperative shutdown that may
+  // never arrive. Normal completion/failure cleanup still uses graceful stop.
+  if (requestOptions.forceKill) {
     try {
-      await docker.stopContainer(containerId, WORKER_STOP_GRACE_SECONDS, requestOptions)
+      await docker.killContainer(containerId, "KILL", requestOptions)
     } catch (error) {
-      if (!isContainerStopAlreadyStoppedError(error)) throw error
+      if (!isContainerKillConflictError(error)) throw error
     }
     inspection = await docker.inspectContainer(containerId, requestOptions)
-    if (typeof inspection?.State?.Running !== "boolean") throw new Error("Worker container state unavailable")
-    if (inspection.State.Running) {
-      try {
-        await docker.killContainer(containerId, "KILL", requestOptions)
-      } catch (error) {
-        if (!isContainerKillConflictError(error)) throw error
-      }
-      inspection = await docker.inspectContainer(containerId, requestOptions)
-      if (inspection?.State?.Running !== false) throw new ContainerCleanupConfirmationError()
+    if (inspection?.State?.Running !== false) throw new ContainerCleanupConfirmationError()
+    await docker.removeContainer(containerId, requestOptions)
+    return
+  }
+  try {
+    await docker.stopContainer(containerId, WORKER_STOP_GRACE_SECONDS, requestOptions)
+  } catch (error) {
+    if (!isContainerStopAlreadyStoppedError(error)) throw error
+  }
+  inspection = await docker.inspectContainer(containerId, requestOptions)
+  if (typeof inspection?.State?.Running !== "boolean") throw new Error("Worker container state unavailable")
+  if (inspection.State.Running) {
+    try {
+      await docker.killContainer(containerId, "KILL", requestOptions)
+    } catch (error) {
+      if (!isContainerKillConflictError(error)) throw error
     }
+    inspection = await docker.inspectContainer(containerId, requestOptions)
+    if (inspection?.State?.Running !== false) throw new ContainerCleanupConfirmationError()
   }
   await docker.removeContainer(containerId, requestOptions)
 }
@@ -907,6 +1137,40 @@ function parseWorkerRecords(text, provider = "codex") {
   return records
 }
 
+/**
+ * Extract a closed provider mutation claim from worker records. The claim
+ * contract is exactly `{type: "mutation_claim", mutations: {worktreeEdit: bool,
+ * commit: bool, push: bool, githubWrite: bool}}`. The claim record is removed
+ * from the returned records so it is never relayed as a worker event.
+ * Malformed claims or multiple claims fail closed and abort reconciliation.
+ * @param {unknown[]} records
+ */
+export function extractMutationClaim(records) {
+  const claims = records.filter((record) => isRecord(record) && record.type === "mutation_claim")
+  if (claims.length === 0) return {records}
+  if (claims.length > 1) throw new Error("Multiple provider mutation claims")
+  const claim = claims[0]
+  if (!exactKeys(claim, ["type", "mutations"])) throw new Error("Malformed provider mutation claim")
+  const mutations = claim.mutations
+  if (!isRecord(mutations) || !exactKeys(mutations, [...MUTATION_CAPABILITIES])) {
+    throw new Error("Malformed provider mutation claim")
+  }
+  const parsed = {
+    worktreeEdit: booleanClaimValue(mutations.worktreeEdit),
+    commit: booleanClaimValue(mutations.commit),
+    push: booleanClaimValue(mutations.push),
+    githubWrite: booleanClaimValue(mutations.githubWrite)
+  }
+  const stripped = records.filter((record) => record !== claim)
+  return {records: stripped, claim: parsed}
+}
+
+/** @param {unknown} value */
+function booleanClaimValue(value) {
+  if (typeof value !== "boolean") throw new Error("Malformed provider mutation claim")
+  return value
+}
+
 function validatedKimiWorkerEnvelope(record) {
   const sessionId = kimiSessionEnvelopeId(record)
   if (sessionId !== undefined) return {type: "session", sessionId}
@@ -959,6 +1223,20 @@ export function demultiplexDockerLogChunks(buffer) {
   return [{channel: "stdout", data: buffer}]
 }
 
+/**
+ * @typedef {{
+ *   provider: "codex" | "kimi",
+ *   profile: string,
+ *   repositoryRoot: string,
+ *   cwd: string,
+ *   providerArguments: string[],
+ *   resumeSession?: string,
+ *   mutationPolicy?: import("./mutation-policy.js").MutationPolicy,
+ *   binding?: unknown
+ * }} PreflightSelection
+ */
+
+/** @param {unknown} value @param {"codex" | "kimi"} [expectedProvider] @returns {PreflightSelection} */
 export function parsePreflight(value, expectedProvider = "codex") {
   if (!isRecord(value) || value.provider !== expectedProvider || (expectedProvider !== "codex" && expectedProvider !== "kimi")
     || typeof value.profile !== "string" || !Array.isArray(value.providerArguments)
@@ -968,30 +1246,36 @@ export function parsePreflight(value, expectedProvider = "codex") {
   if (value.resumeSession !== undefined && (typeof value.resumeSession !== "string" || /[\r\n]/u.test(value.resumeSession))) throw new ClientError("Invalid isolated runtime preflight")
   if (expectedProvider === "kimi") {
     // The Kimi request schema is closed: repositoryRoot/cwd are derived from
-    // the binding, so any extraneous top-level field is rejected rather than
-    // silently ignored.
-    const allowedKeys = ["provider", "profile", "binding", "providerArguments", ...(value.resumeSession === undefined ? [] : ["resumeSession"])]
+    // the binding, and mutationPolicy is the only optional extension.
+    const allowedKeys = ["provider", "profile", "binding", "providerArguments",
+      ...(value.resumeSession === undefined ? [] : ["resumeSession"]),
+      ...(value.mutationPolicy === undefined ? [] : ["mutationPolicy"])]
     if (!exactKeys(value, allowedKeys)) throw new ClientError("Invalid isolated runtime preflight")
     let binding
     try { binding = parseThreadwireBinding(value.binding) } catch { throw new ClientError("Invalid isolated runtime preflight") }
+    const mutationPolicy = value.mutationPolicy === undefined ? undefined : parseMutationPolicy(JSON.stringify(value.mutationPolicy))
     return {
       provider: "kimi", profile: value.profile, binding,
       repositoryRoot: binding.source.target, cwd: binding.runtime.workdir,
       providerArguments: value.providerArguments,
-      ...(value.resumeSession === undefined ? {} : {resumeSession: value.resumeSession})
+      ...(value.resumeSession === undefined ? {} : {resumeSession: value.resumeSession}),
+      ...(mutationPolicy === undefined ? {} : {mutationPolicy})
     }
   }
   if (typeof value.repositoryRoot !== "string" || typeof value.cwd !== "string"
     || !bounded(value.repositoryRoot, 4096) || !bounded(value.cwd, 4096)) throw new ClientError("Invalid isolated runtime preflight")
+  const mutationPolicy = parseMutationPolicy(value.mutationPolicy === undefined ? undefined : JSON.stringify(value.mutationPolicy))
   return {
     provider: "codex", profile: value.profile, repositoryRoot: value.repositoryRoot, cwd: value.cwd,
     providerArguments: value.providerArguments,
-    ...(value.resumeSession === undefined ? {} : {resumeSession: value.resumeSession})
+    ...(value.resumeSession === undefined ? {} : {resumeSession: value.resumeSession}),
+    ...(mutationPolicy === undefined ? {} : {mutationPolicy})
   }
 }
 
 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")) {
+  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")
+    || value.mutationPolicy !== undefined) {
     throw new ClientError("Invalid isolated runtime run")
   }
   if (!bounded(value.preflightId, 64) || !boundedPrompt(value.prompt, 524_288)
@@ -1284,31 +1568,12 @@ function sendJson(response, status, value) {
   response.end(JSON.stringify(value))
 }
 
-function isRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value)
-}
-
-function exactKeys(value, expected) {
-  const actual = Object.keys(value).sort()
-  const wanted = [...expected].sort()
-  return actual.length === wanted.length && actual.every((key, index) => key === wanted[index])
-}
-
-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)
+      server.off("error", reject)
+      resolve()
     })
   })
 }
@@ -1484,6 +1749,24 @@ export async function reconcileDockerResources(docker, brokerContainer, stateReg
       activeLineages.add(identity.lineage)
       continue
     }
+    // Remove any ephemeral per-run git metadata snapshot volume that was created
+    // for a commit-denied run and then left behind by a supervisor crash. Active
+    // runs and runs whose primary cleanup failed are skipped.
+    const snapshots = await docker.listVolumes({
+      "org.threadwire.owner": "isolated-runtime",
+      "org.threadwire.namespace": namespace,
+      "org.threadwire.run": identity.run,
+      "org.threadwire.role": "git-metadata-snapshot"
+    }, requestOptions).catch(() => undefined)
+    if (Array.isArray(snapshots?.Volumes)) {
+      for (const snapshot of snapshots.Volumes) {
+        await docker.removeVolume(snapshot.Name, requestOptions).catch(() => { cleanupFailed.add(identity.run) })
+      }
+    }
+    if (cleanupFailed.has(identity.run)) {
+      activeLineages.add(identity.lineage)
+      continue
+    }
     await stateRegistry.completeRun(identity.run, requestOptions?.signal).catch(() => activeLineages.add(identity.lineage))
   }
   return [...activeLineages]
@@ -1533,17 +1816,30 @@ function ownedContainerIdentity(container, labels, persisted) {
     || typeof container.Config.WorkingDir !== "string" || !within("/worktree", container.Config.WorkingDir)
     || container.HostConfig.NetworkMode !== `${labels.run}-net`
     || !validWorkerSecurity(container.Config, container.HostConfig, labels.provider)
-    || !Array.isArray(container.HostConfig.Mounts) || container.HostConfig.Mounts.length !== 2) return undefined
+    || !Array.isArray(container.HostConfig.Mounts) || (container.HostConfig.Mounts.length !== 2 && container.HostConfig.Mounts.length !== 3)) return undefined
   const inspectedLabels = validResourceLabels(container.Config.Labels, labels.namespace, true, labels.provider)
   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")
+  const gitOverlay = container.HostConfig.Mounts.find((mount) => mount?.Target === "/worktree/.git")
   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
+  if (!validWorktreeMount(worktree, {allowReadOnly: gitOverlay === undefined})) return undefined
+  if (container.HostConfig.Mounts.length === 3) {
+    if (!validGitOverlayMount(gitOverlay, labels.run)) return undefined
+  } else if (gitOverlay !== undefined) {
+    return undefined
+  }
   return runIdentityFrom(labels, container.Config.Image, worktree)
 }
 
+/** @param {unknown} mount @param {string} runId */
+function validGitOverlayMount(mount, runId) {
+  return isRecord(mount) && mount.Type === "volume" && mount.Source === `${runId}-git` && mount.Target === "/worktree/.git"
+    && mount.ReadOnly === true
+    && Object.keys(mount).every((key) => ["Type", "Source", "Target", "ReadOnly"].includes(key))
+}
+
 /**
  * Exact, fail-closed Kimi container identity. The persisted sealed run
  * identity is the single authority for the expected validator, relay, and
@@ -1766,11 +2062,13 @@ function validWorkerSecurity(config, host, provider = "codex") {
       && expected.every((name) => names.filter((entry) => entry === name).length === 1)
       && !names.some((name) => /^(?:CODEX|OPENAI|TELEGRAM|THREADWIRE_KIMI_(?:OAUTH|CONTROL))/u.test(name))
   }
-  if (config.Env.length !== 13 + resumeCount) return false
+  const hasGitOverlay = config.Env.includes("THREADWIRE_GIT_OVERLAY_READ_ONLY=true")
   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"
   ]
+  if (hasGitOverlay) expected.push("THREADWIRE_GIT_OVERLAY_READ_ONLY")
+  if (config.Env.length !== expected.length + 3 + resumeCount) return false
   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=24.19.0") && config.Env.includes("YARN_VERSION=1.22.22")
@@ -1813,8 +2111,9 @@ function ownedKimiNetworkIdentity(network, labels, identity) {
   return true
 }
 
-function validWorktreeMount(mount) {
-  if (!isRecord(mount) || mount.Target !== "/worktree" || mount.ReadOnly === true) return false
+function validWorktreeMount(mount, options = {}) {
+  if (!isRecord(mount) || mount.Target !== "/worktree") return false
+  if (!options.allowReadOnly && 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)