threadwire 0.1.24 → 0.1.26

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 ## Unreleased
 
+- Enforce per-run worker mutation boundaries in isolated runtime. `threadwire run
+  --relay-write` accepts a closed `--mutation-policy <json>` with
+  `{worktreeEdit, commit, push, githubWrite}` booleans; omitted capabilities
+  default to allowed to preserve existing behavior. The policy is sealed at
+  preflight and enforced at container creation: denied worktree edits make the
+  worktree mount read-only, denied commits mount `.git` read-only, denied pushes
+  run with no remote credentials and no egress, and denied GitHub writes remove
+  GitHub CLI/token surfaces. The same policy is now accepted, sealed, and
+  enforced for Kimi runs: denied worktree or commit access makes the Kimi source
+  volume read-only, push denial keeps the worker free of remote credentials, and
+  GitHub-write denial avoids broad GitHub CLI config while preserving the Kimi
+  model-broker relay and exact session-resume behavior. Pre/post run git
+  snapshots capture HEAD, refs, porcelain status, reflog delta, and
+  remote-tracking refs in a credential-free subprocess for both Codex and Kimi;
+  Kimi snapshots run through an offline helper container so source Git state can
+  be observed without exposing credentials. The runtime reconciles observations
+  with the sealed policy and any closed provider `mutation_claim`, failing with
+  exit code 2 when a denied mutation occurs or the provider claim contradicts
+  observations. The `mutation_claim` parser now requires the exact closed schema
+  (`{type, mutations}` with exactly the four boolean capabilities) and rejects
+  malformed or multiple claims as deterministic reconciliation failures. Add
+  focused unit tests and a Docker E2E fixture covering forbidden commit/push and
+  a false "no mutation" provider narrative.
+
+- Harden `threadwire capacity` edge cases. Kimi quota remaining percent is now
+  computed with integer-safe arithmetic so values such as 29 % of 100 no longer
+  lose the inclusive reserve boundary to floating-point rounding. Kimi probe
+  body-read aborts, timeouts, and transport errors are classified as
+  `unavailable`, while oversized bodies and malformed JSON remain `protocol`;
+  no token or response detail is leaked. `--timeout-ms` is now rejected above
+  Node's maximum timer delay (`2147483647`), matching the existing positive
+  integer error convention and updated help text.
+
 - Fix a race in isolated-runtime worker cleanup: Docker's ContainerStop returns
   HTTP 304 when the owned container exits before the stop call, and
   ContainerKill returns HTTP 409 when the container exits between the post-stop

package/docs/delegated-result-protocol.md

@@ -100,6 +100,13 @@ The only optional fields are:
 | `artifactHandles` | array of opaque ASCII IDs or safe POSIX-style paths | 16 entries; 512 characters each |
 | `references` | array of `{kind,value}` | 16 entries; 2,048 code points per value |
 | `validationSummary` | string | 2,048 Unicode code points |
+| `observedMutations` | object | closed `{worktreeEdit,commit,push,githubWrite}` booleans |
+
+`observedMutations` is populated only by the isolated runtime after reconciling
+pre/post run git snapshots with the sealed per-run mutation policy and any closed
+provider `mutation_claim`. A claim that contradicts the observed state makes the
+terminal state `failed` with exit code 2. When the field is absent, callers must
+not infer any mutation policy.
 
 A reference `kind` is exactly `commit` or `url`. Commit values are 7–64
 hexadecimal characters. URL values are non-whitespace HTTP or HTTPS URLs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "threadwire",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "description": "Stream Codex, Claude, Kimi Code, and OpenCode worker progress to an explicit Telegram destination",
   "keywords": [
     "ai-agent",

package/scripts/verify-package.js

@@ -61,6 +61,8 @@ const EXPECTED_FILES = [
   "src/model-broker-policy.js",
   "src/model-broker.js",
   "src/mount-policy.js",
+  "src/mutation-policy.js",
+  "src/mutation-snapshot.js",
   "src/notice-queue.js",
   "src/notifiers/fetch-transport.js",
   "src/notifiers/telegram.js",
@@ -71,6 +73,7 @@ const EXPECTED_FILES = [
   "src/providers/index.js",
   "src/providers/kimi.js",
   "src/providers/opencode.js",
+  "src/record-helpers.js",
   "src/redaction.js",
   "src/provider-capacity-codex.js",
   "src/provider-capacity-kimi.js",

package/src/absolute-deadline.js

@@ -75,6 +75,13 @@ export async function abortable(promise, signal) {
   })
 }
 
+export class ResponseCapacityError extends Error {
+  constructor() {
+    super("Response exceeded capacity")
+    this.name = "ResponseCapacityError"
+  }
+}
+
 export async function readResponseCapped(response, capacity, signal) {
   const reader = response.body?.getReader()
   if (!reader) return Buffer.alloc(0)
@@ -87,8 +94,8 @@ export async function readResponseCapped(response, capacity, signal) {
       const chunk = Buffer.from(value)
       size += chunk.length
       if (size > capacity) {
-        await reader.cancel(new Error("Response exceeded capacity")).catch(() => {})
-        throw new Error("Response exceeded capacity")
+        await reader.cancel(new ResponseCapacityError()).catch(() => {})
+        throw new ResponseCapacityError()
       }
       chunks.push(chunk)
     }

package/src/cli.js

@@ -4,7 +4,7 @@ import {lstat, readFile, readlink, realpath} from "node:fs/promises"
 import {randomUUID} from "node:crypto"
 import {basename, dirname, isAbsolute, join, normalize, resolve} from "node:path"
 import {stdin, stderr, stdout} from "node:process"
-import {createFetchTransport} from "./notifiers/fetch-transport.js"
+import {createFetchTransport, MAX_TIMER_DELAY_MS} from "./notifiers/fetch-transport.js"
 import {createTelegramSender, parseTelegramTarget} from "./notifiers/telegram.js"
 import {createProvider, PROVIDERS} from "./providers/index.js"
 import {runWorker} from "./run-worker.js"
@@ -18,6 +18,7 @@ import {ContextBudgetMetrics} from "./context-budget-metrics.js"
 import {workerEventToIndexEvent} from "./evidence-index.js"
 import {isolatedRuntimeClientFromEnvironment} from "./isolated-runtime-client.js"
 import {validateRelayWriteProviderArguments} from "./relay-write.js"
+import {parseMutationPolicy} from "./mutation-policy.js"
 import {abortable} from "./absolute-deadline.js"
 import {NormalizedOutput} from "./normalized-output.js"
 import {
@@ -34,6 +35,7 @@ import {probeKimiCapacity} from "./provider-capacity-kimi.js"
 const HELP = `Usage: threadwire run --provider <codex|claude|kimi|opencode> --target telegram:<chat-id> | telegram:<chat-id>:<thread-id> | file:<absolute-path>
   [--process-number <positive-integer>] [--cwd <directory>]
   [--relay-write]
+  [--mutation-policy <json>]
   [--tool-messages] [--max-output-length <positive-integer>]
   [--resume-session <provider-session-id>] [--transcript <normalized-jsonl-path>]
   [--activity-log <local-jsonl-path>]
@@ -45,11 +47,11 @@ const HELP = `Usage: threadwire run --provider <codex|claude|kimi|opencode> --ta
   (--summary | --events [--kind <kind>] [--after <order>] [--before <order>] [--limit <positive-integer>] | --failures [--after <order>] [--limit <positive-integer>])
        threadwire capacity [--provider <codex|kimi>]...
   [--short-reserve-percent <0-100>] [--long-reserve-percent <0-100>]
-  [--timeout-ms <positive-integer>]
+  [--timeout-ms <1-2147483647>]
        threadwire status --activity-log <absolute-path>
   (Emits one closed versioned JSON status document from the activity log.)`
 
-/** @typedef {{provider: string, target: string, cwd: string, toolMessages: boolean, relayWrite: boolean, prompt?: string, promptFile?: string, processNumber?: number, maxOutputLength?: number, resumeSession?: string, transcript?: string, activityLog?: string, providerArguments: string[]}} ParsedArguments */
+/** @typedef {{provider: string, target: string, cwd: string, toolMessages: boolean, relayWrite: boolean, mutationPolicy?: import("./mutation-policy.js").MutationPolicy | undefined, prompt?: string, promptFile?: string, processNumber?: number, maxOutputLength?: number, resumeSession?: string, transcript?: string, activityLog?: string, providerArguments: string[]}} ParsedArguments */
 /** @typedef {{evidenceRead: true, request: unknown} | {evidenceInspect: true, request: unknown}} EvidenceParsedArguments */
 /** @typedef {{capacity: true, providers: import("./provider-capacity.js").CapacityProvider[], shortReservePercent: number, longReservePercent: number, timeoutMs: number}} CapacityParsedArguments */
 /** @typedef {{probe: (provider: import("./provider-capacity.js").CapacityProvider, timeoutMs?: number) => Promise<import("./provider-capacity.js").CapacityCandidate>}} CapacityProbeDependency */
@@ -114,6 +116,8 @@ export function parseArguments(arguments_) {
       if (value.includes("\0")) throw new Error("--transcript path is invalid")
       parsed.transcript = resolve(value)
       transcriptProvided = true
+    } else if (option === "--mutation-policy") {
+      parsed.mutationPolicy = parseMutationPolicy(value)
     } else throw new Error(`Unknown option: ${option}`)
     index += 2
   }
@@ -127,6 +131,7 @@ export function parseArguments(arguments_) {
     throw new Error("--transcript and --activity-log must resolve to different paths")
   }
   if (parsed.relayWrite && parsed.provider !== "codex") throw new Error("--relay-write is only supported for codex")
+  if (parsed.mutationPolicy !== undefined && !parsed.relayWrite) throw new Error("--mutation-policy requires --relay-write")
   return /** @type {ParsedArguments} */ (parsed)
 }
 
@@ -231,7 +236,7 @@ function parseCapacityArguments(arguments_) {
       providers.push(provider)
     } else if (option === "--short-reserve-percent") shortReservePercent = reservePercent(value, option)
     else if (option === "--long-reserve-percent") longReservePercent = reservePercent(value, option)
-    else if (option === "--timeout-ms") timeoutMs = positiveInteger(value, option)
+    else if (option === "--timeout-ms") timeoutMs = capacityTimeoutMs(value, option)
     else throw new Error(HELP)
   }
   return {
@@ -383,7 +388,8 @@ export async function main(arguments_, dependencies = {}) {
         repositoryRoot: parsed.cwd,
         cwd: parsed.cwd,
         providerArguments: parsed.providerArguments,
-        ...(parsed.resumeSession === undefined ? {} : {resumeSession: parsed.resumeSession})
+        ...(parsed.resumeSession === undefined ? {} : {resumeSession: parsed.resumeSession}),
+        ...(parsed.mutationPolicy === undefined ? {} : {mutationPolicy: parsed.mutationPolicy})
       })
       : undefined
     const admission = /** @type {DelegatedResultAdmission} */ (runAdmission)
@@ -532,6 +538,11 @@ export async function main(arguments_, dependencies = {}) {
           if (activity && pid !== undefined) activity.recordStarted(provider.name, pid)
         },
         onRecord: (record) => {
+          const recordObject = /** @type {Record<string, unknown> | undefined} */ (isRecord(record) ? record : undefined)
+          if (recordObject !== undefined && recordObject.type === "observed_mutations" && isRecord(recordObject.mutations)) {
+            admission.setObservedMutations(/** @type {import("./mutation-policy.js").MutationPolicy} */ (recordObject.mutations))
+            return
+          }
           metrics.recordParsedProviderRecord("provider_stdout")
           const id = provider.sessionId(record)
           if (id !== undefined) {
@@ -843,6 +854,20 @@ function positiveInteger(value, option) {
   return number
 }
 
+/** @param {string} value @param {string} option */
+function capacityTimeoutMs(value, option) {
+  const number = positiveInteger(value, option)
+  if (number > MAX_TIMER_DELAY_MS) {
+    throw new Error(`${option} must be no greater than ${MAX_TIMER_DELAY_MS}`)
+  }
+  return number
+}
+
+/** @param {unknown} value */
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
 /** @param {string} value */
 function sessionId(value) {
   try {

package/src/delegated-result-admission.js

@@ -1,6 +1,7 @@
 // @ts-check
 
 import {types as utilTypes} from "node:util"
+import {MUTATION_CAPABILITIES} from "./mutation-policy.js"
 import {sanitizeOutput} from "./relay.js"
 
 export const CONCLUSION_LIMIT = 16_384
@@ -24,7 +25,8 @@ const CANDIDATE_FIELDS = new Set([
   "continuationHandle",
   "artifactHandles",
   "references",
-  "validationSummary"
+  "validationSummary",
+  "observedMutations"
 ])
 const STATES = new Set(["completed", "failed", "blocked", "needs_decision"])
 
@@ -40,7 +42,8 @@ const STATES = new Set(["completed", "failed", "blocked", "needs_decision"])
  *   continuationHandle?: string,
  *   artifactHandles?: string[],
  *   references?: AdmissionReference[],
- *   validationSummary?: string
+ *   validationSummary?: string,
+ *   observedMutations?: import("./mutation-policy.js").MutationPolicy
  * }} DelegatedResultCandidate
  */
 
@@ -57,6 +60,8 @@ export class DelegatedResultAdmission {
     this.artifactHandles = []
     /** @type {AdmissionReference[]} */
     this.references = []
+    /** @type {import("./mutation-policy.js").MutationPolicy | undefined} */
+    this.observedMutations = undefined
     this.completed = false
   }
 
@@ -100,6 +105,17 @@ export class DelegatedResultAdmission {
     this.artifactHandles = this.artifactHandles.filter((candidate) => candidate !== handle)
   }
 
+  /** @param {import("./mutation-policy.js").MutationPolicy} value */
+  setObservedMutations(value) {
+    if (
+      typeof value !== "object" || value === null || Array.isArray(value)
+        || !MUTATION_CAPABILITIES.every((capability) => typeof value[capability] === "boolean")
+    ) {
+      throw new Error("Invalid observed mutations")
+    }
+    this.observedMutations = value
+  }
+
   /** @param {{state: TerminalState, exitCode: number}} terminal */
   preview(terminal) {
     return this.createEnvelope(terminal)
@@ -140,7 +156,8 @@ export class DelegatedResultAdmission {
       ...(terminal.state !== "completed" || safeConclusion === undefined ? {} : {conclusion: safeConclusion}),
       ...(this.continuationHandle === undefined ? {} : {continuationHandle: this.continuationHandle}),
       ...(this.artifactHandles.length === 0 ? {} : {artifactHandles: this.artifactHandles}),
-      ...(this.references.length === 0 ? {} : {references: this.references})
+      ...(this.references.length === 0 ? {} : {references: this.references}),
+      ...(this.observedMutations === undefined ? {} : {observedMutations: this.observedMutations})
     })
   }
 }
@@ -166,6 +183,7 @@ export function createDelegatedResultEnvelope(candidate) {
   const validationSummary = optionalBoundedString(clonedCandidate.validationSummary, "validationSummary", VALIDATION_SUMMARY_LIMIT)
   const artifactHandles = optionalArtifactHandles(clonedCandidate.artifactHandles)
   const references = optionalReferences(clonedCandidate.references)
+  const observedMutations = optionalObservedMutations(clonedCandidate.observedMutations)
 
   const envelope = {
     version: 1,
@@ -178,7 +196,8 @@ export function createDelegatedResultEnvelope(candidate) {
     ...(continuationHandle === undefined ? {} : {continuationHandle}),
     ...(artifactHandles === undefined ? {} : {artifactHandles}),
     ...(references === undefined ? {} : {references}),
-    ...(validationSummary === undefined ? {} : {validationSummary})
+    ...(validationSummary === undefined ? {} : {validationSummary}),
+    ...(observedMutations === undefined ? {} : {observedMutations})
   }
   if (Buffer.byteLength(JSON.stringify(envelope), "utf8") > MAX_ENVELOPE_BYTES) {
     throw new Error("Delegated result candidate exceeds the envelope byte limit")
@@ -256,6 +275,27 @@ function optionalReferences(value) {
   })
 }
 
+/** @param {unknown} value */
+function optionalObservedMutations(value) {
+  if (value === undefined) return undefined
+  if (!isPlainObject(value)) throw new Error("Invalid delegated result observedMutations")
+  if (!hasExactEnumerableFields(value, [...MUTATION_CAPABILITIES])) {
+    throw new Error("Invalid delegated result observedMutations")
+  }
+  return {
+    worktreeEdit: booleanCapability(value.worktreeEdit),
+    commit: booleanCapability(value.commit),
+    push: booleanCapability(value.push),
+    githubWrite: booleanCapability(value.githubWrite)
+  }
+}
+
+/** @param {unknown} value */
+function booleanCapability(value) {
+  if (typeof value !== "boolean") throw new Error("Invalid delegated result observedMutations")
+  return value
+}
+
 /**
  * @param {unknown} value
  * @param {"artifactHandles" | "references"} field

package/src/isolated-runtime-client.js

@@ -1,7 +1,7 @@
 // @ts-nocheck
 /* eslint-disable jsdoc/require-jsdoc */
 
-import {AbsoluteDeadline, deadlineAfter, abortable, readResponseCapped} from "./absolute-deadline.js"
+import {AbsoluteDeadline, deadlineAfter, abortable, readResponseCapped, ResponseCapacityError} from "./absolute-deadline.js"
 
 const MAX_RESPONSE_BYTES = 2_097_152
 const MAX_RAW_OUTPUT_BYTES = 1_048_576
@@ -207,7 +207,7 @@ export class IsolatedRuntimeClient {
     try {
       bytes = await readResponseCapped(response, MAX_RESPONSE_BYTES, signal)
     } catch (error) {
-      if (error instanceof Error && error.message === "Response exceeded capacity") throw new Error("Isolated runtime response exceeded the configured capacity", {cause: error})
+      if (error instanceof ResponseCapacityError) throw new Error("Isolated runtime response exceeded the configured capacity", {cause: error})
       throw error
     }
     if (!response.ok) throw new Error(safeRemoteError(bytes))