threadwire 0.1.13 → 0.1.15

package/src/activity-log-status.js

@@ -0,0 +1,291 @@
+// @ts-check
+
+import {isAbsolute, resolve} from "node:path"
+import {open} from "node:fs/promises"
+
+export const ACTIVITY_LOG_READ_CAPACITY = 1_048_576
+
+const KNOWN_TYPES = new Set([
+  "provider-started", "controller-started", "session-available", "activity", "health", "terminal"
+])
+
+const SESSION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,511}$/u
+
+const VALIDATED_FACT_FIELDS = {
+  "provider-started": ["type", "provider", "pid"],
+  "controller-started": ["type", "pid"],
+  "session-available": ["type", "provider", "sessionId"],
+  "activity": ["type", "provider", "kind"],
+  "health": ["type", "provider", "disposition", "category"],
+  "terminal": ["type", "provider", "state", "exitCode"]
+}
+
+const OPTIONAL_FACT_FIELDS = {
+  "provider-started": ["at"],
+  "controller-started": ["at"],
+  "session-available": ["at"],
+  "activity": ["at"],
+  "health": ["retryAfterMs", "at"],
+  "terminal": ["at"]
+}
+
+const PROVIDERS = new Set(["codex", "claude", "kimi", "opencode"])
+const ACTIVITY_KINDS = new Set(["delta", "tool", "lifecycle"])
+const HEALTH_DISPOSITIONS = new Set(["retrying", "blocked"])
+const HEALTH_CATEGORIES = new Set([
+  "authentication", "permission", "rate-limit", "quota", "billing",
+  "model", "network", "protocol", "unknown"
+])
+const TERMINAL_STATES = new Set(["completed", "failed", "cancelled"])
+
+const MAX_SAFE_DATE_MS = 8640000000000000 // Date maximum
+
+/**
+ * @typedef {{version: number, state: "running" | "retrying" | "blocked" | "completed" | "failed" | "cancelled" | "unknown", provider: string | null, controllerPid: number | null, providerPid: number | null, continuationHandle: string | null, startedAt: string | null, lastActivityAt: string | null, quietForMs: number, health: {disposition: "retrying" | "blocked", category: string, retryAfterMs?: number} | null, terminal: {state: "completed" | "failed" | "cancelled", exitCode: number} | null}} StatusDocument
+ */
+
+/** @param {string[]} arguments_ */
+export function parseStatusArguments(arguments_) {
+  if (arguments_[0] !== "status") throw new Error("Usage: threadwire status --activity-log <absolute-path>")
+  const own = arguments_.slice(1)
+  if (own.length !== 2 || own[0] !== "--activity-log") throw new Error("Usage: threadwire status --activity-log <absolute-path>")
+  const path = own[1]
+  if (!path) throw new Error("--activity-log must be an absolute path")
+  const resolved = resolve(path)
+  if (!isAbsolute(path)) throw new Error("--activity-log must be an absolute path")
+  return {activityLog: resolved}
+}
+
+/**
+ * Read and validate an activity log file, with a bounded read capacity to
+ * prevent uncontrolled allocation. Skips at most one incomplete trailing line.
+ * Rejects malformed completed records and records with unsafe field names.
+ * @param {string} path
+ * @returns {Promise<Record<string, unknown>[]>}
+ */
+export async function readActivityLog(path) {
+  const fd = await open(path, "r")
+  try {
+    const stat = await fd.stat()
+    if (stat.size > ACTIVITY_LOG_READ_CAPACITY) throw new Error("Activity log exceeds read capacity")
+    const buffer = Buffer.alloc(stat.size > 0 ? stat.size : 0)
+    let bytesRead = 0
+    while (bytesRead < stat.size) {
+      const result = await fd.read(buffer, bytesRead, stat.size - bytesRead, bytesRead)
+      if (result.bytesRead === 0) break
+      bytesRead += result.bytesRead
+    }
+    return parseActivityLogContent(buffer.toString("utf8", 0, bytesRead))
+  } finally {
+    await fd.close()
+  }
+}
+
+/**
+ * @param {string} content
+ * @returns {Record<string, unknown>[]}
+ */
+function parseActivityLogContent(content) {
+  const lines = content.split("\n")
+  /** @type {Record<string, unknown>[]} */
+  const records = []
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = /** @type {string} */ (lines[index])
+    if (line.trim().length === 0) continue
+    let record
+    try {
+      record = JSON.parse(line)
+    } catch {
+      if (index === lines.length - 1) break
+      throw new Error("Activity log contains an unreadable completed record")
+    }
+    if (!isRecord(record)) throw new Error("Activity log record is not an object")
+    validateRecordSchema(record)
+    records.push(record)
+  }
+  return records
+}
+
+/**
+ * Pure computation: derives a closed status document from an array of
+ * validated activity-log facts.
+ * @param {Record<string, unknown>[]} records
+ * @param {{now?: () => number}} [options]
+ * @returns {StatusDocument}
+ */
+export function computeStatus(records, options = {}) {
+  const now = options.now ?? (() => Date.now())
+  const clock = now()
+  if (!Number.isSafeInteger(clock) || clock < 0 || clock > MAX_SAFE_DATE_MS) throw new Error("Clock must be a safe non-negative Date-range integer")
+
+  let providerStarted = null
+  /** @type {number | null} */
+  let controllerPid = null
+  /** @type {string | null} */
+  let continuationHandle = null
+  /** @type {{disposition: "retrying" | "blocked", category: string, retryAfterMs?: number} | null} */
+  let health = null
+  /** @type {{state: "completed" | "failed" | "cancelled", exitCode: number} | null} */
+  let terminal = null
+  let sawTerminal = false
+  /** @type {number | null} */
+  let startedAt = null
+  /** @type {number | null} */
+  let lastActivityAt = null
+  let lastHealthIndex = -1
+  let lastActivityIndex = -1
+
+  for (let index = 0; index < records.length; index += 1) {
+    const record = /** @type {Record<string, unknown>} */ (records[index])
+    // Validate timestamps on every record, since computeStatus may be
+    // called directly (not through readActivityLog).
+    const atValue = record.at
+    if (atValue !== undefined && (typeof atValue !== "number" || !Number.isSafeInteger(atValue) || atValue < 0 || atValue > MAX_SAFE_DATE_MS)) {
+      throw new Error("Invalid timestamp")
+    }
+    const type = record.type
+    if (typeof type !== "string" || !KNOWN_TYPES.has(type)) {
+      throw new Error(`Unknown activity log record type: ${String(type)}`)
+    }
+    if (type === "provider-started") {
+      if (providerStarted !== null) throw new Error("Duplicate provider-started record")
+      providerStarted = record
+      if (typeof atValue === "number" && startedAt === null) startedAt = atValue
+      else lastActivityAt = lastActivityAt ?? null
+    } else if (type === "controller-started") {
+      const pid = record.pid
+      if (typeof pid !== "number" || !Number.isSafeInteger(pid) || pid <= 0) {
+        throw new Error("Invalid controller PID in activity log")
+      }
+      controllerPid = pid
+      if (typeof atValue === "number" && startedAt === null) startedAt = atValue
+      if (typeof atValue === "number") lastActivityAt = atValue
+    } else if (type === "session-available") {
+      const id = typeof record.sessionId === "string" ? record.sessionId : null
+      if (id !== null && !SESSION_ID_PATTERN.test(id)) throw new Error("Invalid continuation handle in activity log")
+      continuationHandle = id
+      if (typeof atValue === "number") lastActivityAt = atValue
+    } else if (type === "activity") {
+      lastActivityIndex = index
+      if (typeof atValue === "number") lastActivityAt = atValue
+    } else if (type === "health") {
+      if (sawTerminal) throw new Error("Health record appears after terminal")
+      lastHealthIndex = index
+      health = {
+        disposition: /** @type {"retrying" | "blocked"} */ (record.disposition),
+        category: /** @type {string} */ (record.category)
+      }
+      if (typeof record.retryAfterMs === "number") health.retryAfterMs = record.retryAfterMs
+      if (typeof atValue === "number") lastActivityAt = atValue
+      // Blocked stays sticky regardless; terminal always overrides later.
+    } else if (type === "terminal") {
+      if (sawTerminal) throw new Error("Duplicate terminal record")
+      sawTerminal = true
+      terminal = {
+        state: /** @type {"completed" | "failed" | "cancelled"} */ (record.state),
+        exitCode: /** @type {number} */ (record.exitCode)
+      }
+      if (typeof atValue === "number") lastActivityAt = atValue
+    }
+  }
+
+  // Activity that appears after a retrying health event clears it back to running.
+  // Blocked health stays sticky until terminal overrides it.
+  if (health !== null && health.disposition === "retrying" && lastActivityIndex > lastHealthIndex) {
+    health = null
+  }
+
+  /** @type {number | null} */
+  let effectiveStart = startedAt
+  const ps = providerStarted
+  if (effectiveStart === null && ps !== null && typeof ps.at === "number") {
+    effectiveStart = /** @type {number} */ (ps.at)
+  }
+
+  const state = terminal !== null
+    ? terminal.state
+    : health !== null
+      ? (health.disposition === "blocked" ? "blocked" : "retrying")
+      : ps !== null
+        ? "running"
+        : "unknown"
+
+  const quietForMs = lastActivityAt === null || lastActivityAt === undefined
+    ? (effectiveStart === null ? 0 : Math.max(0, clock - effectiveStart))
+    : Math.max(0, clock - lastActivityAt)
+
+  return {
+    version: 1,
+    state,
+    provider: ps !== null && typeof ps.provider === "string"
+      ? ps.provider
+      : null,
+    controllerPid,
+    providerPid: ps !== null && typeof ps.pid === "number"
+      ? /** @type {number} */ (ps.pid)
+      : null,
+    continuationHandle,
+    startedAt: effectiveStart === null ? null : new Date(effectiveStart).toISOString(),
+    lastActivityAt: lastActivityAt === null ? null : new Date(lastActivityAt).toISOString(),
+    quietForMs,
+    health,
+    terminal
+  }
+}
+
+/**
+ * Validate a single activity-log record against the closed schema.
+ * @param {Record<string, unknown>} record
+ */
+function validateRecordSchema(record) {
+  const type = record.type
+  if (typeof type !== "string") throw new Error("Activity log record missing type")
+  const requiredFields = VALIDATED_FACT_FIELDS[/** @type {keyof typeof VALIDATED_FACT_FIELDS} */ (type)]
+  if (requiredFields === undefined) throw new Error(`Unknown activity log record type: ${type}`)
+  const optionalFields = OPTIONAL_FACT_FIELDS[/** @type {keyof typeof OPTIONAL_FACT_FIELDS} */ (type)] ?? []
+  const allowed = new Set([...requiredFields, ...optionalFields])
+
+  const actual = Object.keys(record)
+  for (const field of actual) {
+    if (!allowed.has(field)) throw new Error(`Unexpected field in ${type} record: ${field}`)
+  }
+  for (const field of requiredFields) {
+    if (!(field in record)) throw new Error(`Missing required field in ${type} record: ${field}`)
+  }
+
+  if (type === "provider-started") {
+    if (typeof record.provider !== "string" || !PROVIDERS.has(record.provider)) throw new Error("Invalid provider")
+    if (typeof record.pid !== "number" || !Number.isSafeInteger(record.pid) || record.pid <= 0) throw new Error("Invalid pid")
+  } else if (type === "controller-started") {
+    if (typeof record.pid !== "number" || !Number.isSafeInteger(record.pid) || record.pid <= 0) throw new Error("Invalid pid")
+  } else if (type === "session-available") {
+    if (typeof record.provider !== "string" || !PROVIDERS.has(record.provider)) throw new Error("Invalid provider")
+    if (typeof record.sessionId !== "string") throw new Error("Invalid sessionId")
+  } else if (type === "activity") {
+    if (typeof record.provider !== "string" || !PROVIDERS.has(record.provider)) throw new Error("Invalid provider")
+    if (typeof record.kind !== "string" || !ACTIVITY_KINDS.has(record.kind)) throw new Error("Invalid activity kind")
+  } else if (type === "health") {
+    if (typeof record.provider !== "string" || !PROVIDERS.has(record.provider)) throw new Error("Invalid provider")
+    if (typeof record.disposition !== "string" || !HEALTH_DISPOSITIONS.has(record.disposition)) throw new Error("Invalid health disposition")
+    if (typeof record.category !== "string" || !HEALTH_CATEGORIES.has(record.category)) throw new Error("Invalid health category")
+    if (record.retryAfterMs !== undefined) {
+      if (typeof record.retryAfterMs !== "number" || !Number.isSafeInteger(record.retryAfterMs) || record.retryAfterMs <= 0) {
+        throw new Error("Invalid retryAfterMs")
+      }
+    }
+  } else if (type === "terminal") {
+    if (typeof record.provider !== "string" || !PROVIDERS.has(record.provider)) throw new Error("Invalid provider")
+    if (typeof record.state !== "string" || !TERMINAL_STATES.has(record.state)) throw new Error("Invalid terminal state")
+    if (typeof record.exitCode !== "number" || !Number.isSafeInteger(record.exitCode) || record.exitCode < 0 || record.exitCode > 255) {
+      throw new Error("Invalid exitCode")
+    }
+  }
+  if (record.at !== undefined && (typeof record.at !== "number" || !Number.isSafeInteger(record.at) || record.at < 0 || record.at > MAX_SAFE_DATE_MS)) {
+    throw new Error("Invalid timestamp")
+  }
+}
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}

package/src/activity-log.js

@@ -4,11 +4,38 @@ import {closeSync, openSync, writeSync} from "node:fs"
 
 const SESSION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,511}$/u
 
+const ACTIVITY_KINDS = new Set(["delta", "tool", "lifecycle"])
+const HEALTH_DISPOSITIONS = new Set(["retrying", "blocked"])
+const HEALTH_CATEGORIES = new Set([
+  "authentication", "permission", "rate-limit", "quota", "billing",
+  "model", "network", "protocol", "unknown"
+])
+const TERMINAL_STATES = new Set(["completed", "failed", "cancelled"])
+
+const SIGNAL_CANCELLED_EXIT_CODES = new Set([130, 143])
+
+const ACTIVITY_THROTTLE_MS = 5000
+
 export class ActivityLog {
-  /** @param {string} path */
-  constructor(path) {
+  /**
+   * @param {string} path
+   * @param {{now?: () => number}} [options]
+   */
+  constructor(path, options = {}) {
     this.fileDescriptor = openSync(path, "a", 0o600)
     this.closed = false
+    this.now = options.now ?? (() => Date.now())
+    this.terminalWritten = false
+    /** @type {string | null} */
+    this.lastHealthFingerprint = null
+    this.lastActivityAt = -ACTIVITY_THROTTLE_MS
+    this.activityCount = 0
+  }
+
+  /** @param {number} pid */
+  recordController(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0) throw new Error("Controller PID is unavailable")
+    this.write({type: "controller-started", pid})
   }
 
   /** @param {"codex" | "claude" | "kimi" | "opencode"} provider @param {number} pid */
@@ -23,15 +50,76 @@ export class ActivityLog {
     this.write({type: "session-available", provider, sessionId})
   }
 
+  /**
+   * @param {"codex" | "claude" | "kimi" | "opencode"} provider
+   * @param {"delta" | "tool" | "lifecycle"} kind
+   */
+  recordActivity(provider, kind) {
+    if (!ACTIVITY_KINDS.has(kind)) throw new Error(`Unknown activity kind: ${kind}`)
+    const now = this.now()
+    if (now - this.lastActivityAt < ACTIVITY_THROTTLE_MS) return
+    this.lastActivityAt = now
+    this.activityCount += 1
+    this.write({type: "activity", provider, kind})
+  }
+
+  /**
+   * @param {"codex" | "claude" | "kimi" | "opencode"} provider
+   * @param {{disposition: "retrying" | "blocked", category: "authentication" | "permission" | "rate-limit" | "quota" | "billing" | "model" | "network" | "protocol" | "unknown", retryAfterMs?: number}} health
+   */
+  recordHealth(provider, health) {
+    if (!HEALTH_DISPOSITIONS.has(health.disposition)) throw new Error("Unknown health disposition")
+    if (!HEALTH_CATEGORIES.has(health.category)) throw new Error("Unknown health category")
+    if (health.retryAfterMs !== undefined) {
+      if (!Number.isSafeInteger(health.retryAfterMs) || health.retryAfterMs <= 0) throw new Error("retryAfterMs must be a positive safe integer")
+      if (health.disposition !== "retrying") throw new Error("retryAfterMs is only valid for retrying disposition")
+    }
+    const fingerprint = `${health.disposition}\0${health.category}\0${health.retryAfterMs ?? ""}`
+    if (fingerprint === this.lastHealthFingerprint) return
+    this.lastHealthFingerprint = fingerprint
+    /** @type {{type: string, provider: string, disposition: string, category: string, retryAfterMs?: number}} */
+    const fact = {type: "health", provider, disposition: health.disposition, category: health.category}
+    if (health.retryAfterMs !== undefined) fact.retryAfterMs = health.retryAfterMs
+    this.write(fact)
+  }
+
+  /**
+   * @param {"codex" | "claude" | "kimi" | "opencode"} provider
+   * @param {"completed" | "failed" | "cancelled"} state
+   * @param {number} exitCode
+   */
+  recordTerminal(provider, state, exitCode) {
+    if (this.terminalWritten) return
+    if (!TERMINAL_STATES.has(state)) throw new Error("Unknown terminal state")
+    if (!Number.isSafeInteger(exitCode) || exitCode < 0 || exitCode > 255) throw new Error("exitCode must be an integer between 0 and 255")
+    this.terminalWritten = true
+    this.write({type: "terminal", provider, state, exitCode})
+  }
+
   close() {
     if (this.closed) return
     this.closed = true
     closeSync(this.fileDescriptor)
   }
 
-  /** @param {{type: "provider-started", provider: "codex" | "claude" | "kimi" | "opencode", pid: number} | {type: "session-available", provider: "codex" | "claude" | "kimi" | "opencode", sessionId: string}} fact */
+  /**
+   * @param {Record<string, unknown>} fact
+   */
   write(fact) {
     if (this.closed) throw new Error("Activity log is closed")
+    fact.at = this.now()
     writeSync(this.fileDescriptor, `${JSON.stringify(fact)}\n`)
   }
 }
+
+/**
+ * Classify a terminal exit code. Known signal-derived codes (130 = SIGINT,
+ * 143 = SIGTERM) map to cancelled; all others map to completed (0) or failed
+ * (nonzero). This is the only place that picks the terminal state constant.
+ * @param {number} exitCode
+ * @returns {"completed" | "failed" | "cancelled"}
+ */
+export function terminalState(exitCode) {
+  if (SIGNAL_CANCELLED_EXIT_CODES.has(exitCode)) return "cancelled"
+  return exitCode === 0 ? "completed" : "failed"
+}

package/src/cli.js

@@ -8,7 +8,8 @@ import {createFetchTransport} 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"
-import {ActivityLog} from "./activity-log.js"
+import {ActivityLog, terminalState} from "./activity-log.js"
+import {computeStatus, parseStatusArguments, readActivityLog} from "./activity-log-status.js"
 import {DelegatedResultAdmission, validateContinuationHandle} from "./delegated-result-admission.js"
 import {buildProviderEnvironment, collectEvidenceRedactions, parseTelegramRequestTimeoutMs, resolveFileBackedSettings} from "./telegram-ingress/config.js"
 import {WorkerControl} from "./worker-control.js"
@@ -18,6 +19,16 @@ import {isolatedRuntimeClientFromEnvironment} from "./isolated-runtime-client.js
 import {validateRelayWriteProviderArguments} from "./relay-write.js"
 import {abortable} from "./absolute-deadline.js"
 import {NormalizedOutput} from "./normalized-output.js"
+import {
+  CAPACITY_PROVIDERS,
+  DEFAULT_CAPACITY_TIMEOUT_MS,
+  DEFAULT_LONG_RESERVE_PERCENT,
+  DEFAULT_SHORT_RESERVE_PERCENT,
+  createCapacityProbe,
+  selectProvider
+} from "./provider-capacity.js"
+import {probeCodexCapacity} from "./provider-capacity-codex.js"
+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>
   [--process-number <positive-integer>] [--cwd <directory>]
@@ -28,10 +39,17 @@ const HELP = `Usage: threadwire run --provider <codex|claude|kimi|opencode> --ta
   [--prompt <text> | --prompt-file <path> | stdin]
   [-- <provider arguments...>]
        threadwire evidence read --handle <opaque-handle>
-  (--bytes <offset>:<limit> | --lines <start>:<limit> | --query <literal> --context-bytes <limit>)`
+  (--bytes <offset>:<limit> | --lines <start>:<limit> | --query <literal> --context-bytes <limit>)
+       threadwire capacity [--provider <codex|kimi>]...
+  [--short-reserve-percent <0-100>] [--long-reserve-percent <0-100>]
+  [--timeout-ms <positive-integer>]
+       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 {{evidenceRead: 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 */
 /**
  * @typedef {{
  *   env?: NodeJS.ProcessEnv,
@@ -43,7 +61,9 @@ const HELP = `Usage: threadwire run --provider <codex|claude|kimi|opencode> --ta
  *   evidenceStore?: EvidenceStore,
  *   evidenceOwnerScope?: {destinationId: string, runId: string},
  *   workerControlOptions?: Pick<ConstructorParameters<typeof WorkerControl>[0], "queueOptions">,
- *   isolatedRuntimeClient?: Pick<import("./isolated-runtime-client.js").IsolatedRuntimeClient, "preflight" | "run">
+ *   isolatedRuntimeClient?: Pick<import("./isolated-runtime-client.js").IsolatedRuntimeClient, "preflight" | "startRun">,
+ *   capacityProbe?: CapacityProbeDependency,
+ *   now?: () => number
  * }} MainDependencies
  */
 
@@ -135,6 +155,71 @@ function parseEvidenceArguments(arguments_) {
   return {evidenceRead: true, request}
 }
 
+/** @param {string[]} arguments_ @returns {CapacityParsedArguments | {help: true}} */
+function parseCapacityArguments(arguments_) {
+  if (arguments_.includes("--help") || arguments_.includes("-h")) return {help: true}
+  /** @type {import("./provider-capacity.js").CapacityProvider[]} */
+  const providers = []
+  let shortReservePercent = DEFAULT_SHORT_RESERVE_PERCENT
+  let longReservePercent = DEFAULT_LONG_RESERVE_PERCENT
+  let timeoutMs = DEFAULT_CAPACITY_TIMEOUT_MS
+  /** @type {Set<string>} */
+  const seen = new Set()
+  for (let index = 1; index < arguments_.length; index += 2) {
+    const option = arguments_[index]
+    const value = arguments_[index + 1]
+    if (!option || value === undefined) throw new Error(HELP)
+    if (option !== "--provider") {
+      if (seen.has(option)) throw new Error(`Duplicate capacity option: ${option}`)
+      seen.add(option)
+    }
+    if (option === "--provider") {
+      if (!CAPACITY_PROVIDERS.includes(/** @type {import("./provider-capacity.js").CapacityProvider} */ (value))) {
+        throw new Error(`--provider must be one of: ${CAPACITY_PROVIDERS.join(", ")}`)
+      }
+      const provider = /** @type {import("./provider-capacity.js").CapacityProvider} */ (value)
+      if (providers.includes(provider)) throw new Error(`Duplicate capacity provider: ${value}`)
+      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 throw new Error(HELP)
+  }
+  return {
+    capacity: true,
+    providers: providers.length === 0 ? [...CAPACITY_PROVIDERS] : providers,
+    shortReservePercent,
+    longReservePercent,
+    timeoutMs
+  }
+}
+
+/**
+ * The real probe never rejects (it converts failures into candidates); this
+ * guard keeps any probe implementation from leaking an unexpected error into
+ * output by degrading to a fixed, credential-free candidate.
+ * @param {CapacityProbeDependency} probe
+ * @param {import("./provider-capacity.js").CapacityProvider} provider
+ * @param {number} timeoutMs
+ * @returns {Promise<import("./provider-capacity.js").CapacityCandidate>}
+ */
+async function probeCapacityCandidate(probe, provider, timeoutMs) {
+  try {
+    return await probe.probe(provider, timeoutMs)
+  } catch {
+    return {provider, status: "unavailable", error: "Capacity probe failed"}
+  }
+}
+
+/** @param {string} value @param {string} option */
+function reservePercent(value, option) {
+  const number = Number(value)
+  if (!/^\d+$/u.test(value) || !Number.isSafeInteger(number) || number > 100) {
+    throw new Error(`${option} must be an integer between 0 and 100`)
+  }
+  return number
+}
+
 /** @param {string} value @param {boolean} zeroStart */
 function rangePair(value, zeroStart) {
   const match = /^(\d+):(\d+)$/u.exec(value)
@@ -162,11 +247,51 @@ export async function main(arguments_, dependencies = {}) {
   /** @type {DelegatedResultAdmission | undefined} */
   let runAdmission
   try {
-    const parsed = arguments_[0] === "evidence" ? parseEvidenceArguments(arguments_) : parseArguments(arguments_)
+    if (arguments_[0] === "status") {
+      const statusParsed = parseStatusArguments(arguments_)
+      if (validateOnly) return 0
+      const records = await readActivityLog(statusParsed.activityLog)
+      const status = computeStatus(records, {
+        ...(dependencies.now === undefined ? {} : {now: dependencies.now})
+      })
+      output.write(`${JSON.stringify(status)}\n`)
+      return 0
+    }
+    const parsed = arguments_[0] === "evidence"
+      ? parseEvidenceArguments(arguments_)
+      : arguments_[0] === "capacity" ? parseCapacityArguments(arguments_) : parseArguments(arguments_)
     if ("help" in parsed) {
       if (!validateOnly) output.write(`${HELP}\n`)
       return 0
     }
+    if ("capacity" in parsed) {
+      if (validateOnly) return 0
+      const probe = dependencies.capacityProbe ?? createCapacityProbe({
+        env: sourceEnvironment,
+        probes: {
+          codex: ({env, timeoutMs}) => probeCodexCapacity({env, timeoutMs}),
+          kimi: ({env, timeoutMs}) => probeKimiCapacity({env, timeoutMs})
+        }
+      })
+      /** @type {import("./provider-capacity.js").CapacityCandidate[]} */
+      const candidates = []
+      for (const provider of parsed.providers) {
+        candidates.push(await probeCapacityCandidate(probe, provider, parsed.timeoutMs))
+      }
+      const {selection, rejected} = selectProvider(candidates, {
+        shortReservePercent: parsed.shortReservePercent,
+        longReservePercent: parsed.longReservePercent
+      })
+      output.write(`${JSON.stringify({
+        version: 1,
+        generatedAt: new Date((dependencies.now ?? Date.now)()).toISOString(),
+        reserves: {shortPercent: parsed.shortReservePercent, longPercent: parsed.longReservePercent},
+        candidates,
+        rejected,
+        selection
+      })}\n`)
+      return selection === null ? 2 : 0
+    }
     if ("evidenceRead" in parsed) {
       const root = evidenceRoot(sourceEnvironment.THREADWIRE_EVIDENCE_ROOT)
       if (!root) throw new Error("THREADWIRE_EVIDENCE_ROOT is required")
@@ -261,6 +386,7 @@ export async function main(arguments_, dependencies = {}) {
         metrics
       })
       activity = parsed.activityLog === undefined ? undefined : new ActivityLog(parsed.activityLog)
+      activity?.recordController(process.pid)
       /** @type {import("./run-worker.js").RunWorkerOptions} */
       const workerOptions = {
         executable: provider.executable,
@@ -269,11 +395,16 @@ export async function main(arguments_, dependencies = {}) {
         environment: providerEnvironment,
         provider: provider.name,
         parse: provider.parse,
+        ...(provider.completion === undefined ? {} : {completion: provider.completion}),
+        ...(launchDeadline === undefined ? {} : {signal: launchDeadline.signal}),
         onEvent: (event) => {
           validateNormalizedWorkerEvent(event)
           if (event.type !== "text-delta") {
             metrics.recordRejected(`${event.type}_progress`, Buffer.byteLength(JSON.stringify(event), "utf8"))
           }
+          if (event.type === "text-delta") activity?.recordActivity(provider.name, "delta")
+          else if (event.type === "tool") activity?.recordActivity(provider.name, "tool")
+          else if (event.type === "lifecycle") activity?.recordActivity(provider.name, "lifecycle")
           acceptAdmissionEvent(admission, event)
           return control.accept(event)
         },
@@ -287,6 +418,8 @@ export async function main(arguments_, dependencies = {}) {
             admission.setContinuationHandle(id)
             activity?.recordSession(provider.name, id)
           }
+          const health = provider.health(record)
+          if (health !== undefined) activity?.recordHealth(provider.name, health)
         },
         onStdoutChunk: (chunk) => {
           metrics.recordRawChildChunk("provider_stdout", chunk.length)
@@ -301,8 +434,9 @@ export async function main(arguments_, dependencies = {}) {
           return evidence.append("provider-stderr", chunk).then(() => { evidencePayloadBytes += chunk.length })
         }
       }
-      const exitCode = usesIsolatedRuntime
-        ? await /** @type {NonNullable<typeof isolatedRuntimeClient>} */ (isolatedRuntimeClient).run({
+      let exitCode
+      if (usesIsolatedRuntime) {
+        const isolatedRun = /** @type {NonNullable<typeof isolatedRuntimeClient>} */ (isolatedRuntimeClient).startRun({
           preflightId: /** @type {{preflightId: string}} */ (isolatedPreflight).preflightId,
           prompt,
           providerArguments: parsed.providerArguments,
@@ -313,7 +447,15 @@ export async function main(arguments_, dependencies = {}) {
           ...(parsed.provider === "kimi" || workerOptions.onStderrChunk === undefined ? {} : {onStderrChunk: workerOptions.onStderrChunk}),
           ...(launchDeadline === undefined ? {} : {deadline: launchDeadline})
         })
-        : await (dependencies.workerRunner ?? runWorker)(workerOptions)
+        try {
+          exitCode = await abortable(isolatedRun.completion, launchDeadline?.signal)
+        } catch (error) {
+          await isolatedRun.cancel(error instanceof Error ? error : new Error("Isolated runtime run failed"))
+          throw error
+        }
+      } else {
+        exitCode = await (dependencies.workerRunner ?? runWorker)(workerOptions)
+      }
       await boundedLaunch(control.close(), launchDeadline)
       terminalExitCode = exitCode
     } finally {
@@ -336,7 +478,10 @@ export async function main(arguments_, dependencies = {}) {
       }
       admission.complete({state: terminalExitCode === 0 ? "completed" : "failed", exitCode: terminalExitCode})
       errorOutput.write(`threadwire-context-metrics ${JSON.stringify(metrics.conciseDiagnostic())}\n`)
-      activity?.close()
+      if (activity !== undefined) {
+        activity.recordTerminal(/** @type {"codex" | "claude" | "kimi" | "opencode"} */ (parsed.provider), terminalState(terminalExitCode), terminalExitCode)
+        activity.close()
+      }
       await boundedLaunch(ownedEvidenceStore?.close(), launchDeadline).catch(() => {})
       launchDeadline?.close()
     }