threadwire 0.1.25 → 0.1.26

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## 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

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.25",
+  "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/cli.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>]
@@ -49,7 +51,7 @@ const HELP = `Usage: threadwire run --provider <codex|claude|kimi|opencode> --ta
        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)
 }
 
@@ -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) {
@@ -852,6 +863,11 @@ function capacityTimeoutMs(value, option) {
   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