threadwire 0.1.14 → 0.1.15

package/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+## 0.1.15 - 2026-08-03
+
+- Add machine-readable run health supervision: the existing append-only `--activity-log` now records safe timestamped controller/provider/session/activity/health/terminal facts with an explicit `controller-started` fact (the run controller's own PID, not an injected status-process PID). The `threadwire status --activity-log <absolute-path>` read-only command emits exactly one closed versioned JSON document (`version`, `state`, `provider`, `controllerPid`, `providerPid`, `continuationHandle`, `startedAt`, `lastActivityAt`, `quietForMs`, `health`, `terminal`). PIDs are recorded non-authoritative facts; status never inspects or signals processes. Health events carry a bounded disposition (`retrying`/`blocked`) plus safe category (`authentication`/`permission`/`rate-limit`/`quota`/`billing`/`model`/`network`/`protocol`/`unknown`) and optional `retryAfterMs` in milliseconds, extracted only from an explicit small list of safe provider record containers (top-level record and known nested `error`/`part`/`part.error`/`.data` shapes) — never recursive traversal and never message/text regex. Generic HTTP 429 → retrying/rate-limit; structured `exceeded_current_quota_error`/`insufficient_quota`/`insufficient_balance` → blocked quota/billing; ambiguous short fields such as `retry_after` (seconds) are never interpreted as milliseconds. If a provider protocol suppresses upstream error details (e.g., real Moonshot OpenCode sessions), no health fact is recorded and status stays running/unknown; Hermes must perform an independent bounded provider probe. Activity records are throttled (5 s) with guaranteed first-activity recording. Terminal facts always override earlier retrying/blocked health state and are written exactly once for local and isolated-runtime run paths; signal-derived exit codes 130/143 record as `cancelled`, all others as `completed` (0) or `failed` (nonzero). A later normal activity record clears a prior `retrying` health back to running; `blocked` stays sticky until terminal overrides it. The status command reads the log within a documented 1 MiB byte cap, never opens the file writable, skips at most one incomplete trailing JSONL record, rejects malformed/schema-unsafe records and overlong/malformed continuation handles, validates timestamps as safe non-negative Date-range integers and the injected clock similarly, and never claims stalled/dead from silence. Existing backward-compatible records without timestamps remain readable.
 - Incrementally spool oversized provider JSONL records to private per-record temporary files after the bounded in-memory threshold, preserving byte order, UTF-8 chunk boundaries, malformed/incomplete-record diagnostics, and the exact absolute record cap while cleaning every per-record spill directory on success, failure, and cancellation. Protocol completion stops same-chunk scanning before any trailing record can exceed the cap or emit output. Ordinary valid provider records are no longer constrained to Telegram display sizes. Container-backed cancellation and failure teardown now retain exact Docker ownership through inspect, bounded TERM stop, terminal-state confirmation, and exact-container KILL escalation; CLI and Telegram deadline cancellation close the request side, await bounded terminal cleanup confirmation, and never treat an HTTP abort as cleanup success. Unconfirmed cleanup remains sealed for reconciliation and can never report success. Direct local-process behavior is unchanged.
 - Extend the checked-in development image with build-time `oc-codex-multi-auth`, DeepSeek OpenAI-compatible, and xAI provider runtimes plus a root-owned secret-free OpenCode catalog for GPT-5.6 Sol/Terra/Luna, DeepSeek V4 Pro/Flash, Grok 4.5/Build/Code Fast, and Kimi K3 through OpenCode's built-in `moonshotai` provider. Kimi K3 keeps its 1,048,576-token context, 131,072-token output limit, default `max` reasoning effort, and `low`/`high`/`max` variants. Compose now requires portable source paths for native Codex auth, OpenCode auth, plugin OAuth, and the plugin's global account pool; refreshable files mount narrowly read-write, GitHub/context mounts stay read-only, per-project Codex account copies are disabled, and OpenCode database/session/cache state remains in the dedicated development home. The UID/GID 1000 initializer creates every nested mount target without receiving credentials. Threadwire remains the worker boundary; direct OpenCode is for authentication, discovery, and bounded smoke checks only.
 

package/README.md

@@ -86,7 +86,9 @@ Pass `--resume-session <exact-provider-session-id>` to continue a stored Codex,
 
 Pass `--transcript <path>` to capture the exact normalized, caller-facing JSONL protocol written to run stdout. The file is created privately (mode `0600`), must not already exist, and contains the same records in the same byte order as stdout. It never contains provider JSONL, reasoning, tool payloads, prompts, stderr, or credentials.
 
-`--activity-log <path>` is different: it retains its append contract and writes only minimal safe lifecycle facts—provider start (`provider`, child `pid`) and available native session ID. It is local-only and never enters Telegram or normalized stdout.
+`--activity-log <path>` is different: it retains its append contract and writes safe timestamped lifecycle facts—provider start (`provider`, child `pid`), available native session ID, throttled activity markers, structured health events (bounded `retrying`/`blocked` disposition with safe category), and exactly one terminal fact. It is local-only and never enters Telegram or normalized stdout.
+
+Inspect a live or completed activity log with the read-only `threadwire status --activity-log <absolute-path>` command. It emits exactly one closed versioned JSON document with `version`, `state` (`running`/`retrying`/`blocked`/`completed`/`failed`/`cancelled`/`unknown`), `provider`, `controllerPid`, `providerPid`, `continuationHandle`, `startedAt`, `lastActivityAt`, `quietForMs`, `health` (or `null`), and `terminal` (or `null`). The command derives state from the file only, never opens it writable, never inspects or signals processes, and never claims stalled/dead from silence. PIDs are recorded facts with explicit non-authoritative semantics.
 
 Provider stdout is decoded as JSONL with a finite 1 MiB UTF-8 byte limit for each pending unterminated record. Exceeding it rejects the run, removes listeners and signal handlers, and terminates the provider without parsing or rendering the oversized content.
 

package/package.json

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

package/scripts/verify-package.js

@@ -42,6 +42,7 @@ const EXPECTED_FILES = [
   "scripts/verify-package.js",
   "src/absolute-deadline.js",
   "src/activity-log.js",
+  "src/activity-log-status.js",
   "src/normalized-output.js",
   "src/cli.js",
   "src/context-budget-metrics.js",

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"
@@ -41,7 +42,9 @@ const HELP = `Usage: threadwire run --provider <codex|claude|kimi|opencode> --ta
   (--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>]`
+  [--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 */
@@ -244,6 +247,16 @@ export async function main(arguments_, dependencies = {}) {
   /** @type {DelegatedResultAdmission | undefined} */
   let runAdmission
   try {
+    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_)
@@ -373,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,
@@ -388,6 +402,9 @@ export async function main(arguments_, dependencies = {}) {
           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)
         },
@@ -401,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)
@@ -459,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()
     }

package/src/providers/index.js

@@ -6,7 +6,8 @@ import {buildKimiCommand, createKimiCompletion, createKimiParser, createKimiSess
 import {buildOpenCodeCommand, createOpenCodeParser, createOpenCodeSessionId} from "./opencode.js"
 
 /**
- * @typedef {{name: "codex" | "claude" | "kimi" | "opencode", executable: string, arguments: string[], parse: (record: unknown) => import("../types.js").WorkerEvent[], sessionId: (record: unknown) => string | undefined, completion?: (record: unknown) => boolean}} Provider
+ * @typedef {{disposition: "retrying" | "blocked", category: "authentication" | "permission" | "rate-limit" | "quota" | "billing" | "model" | "network" | "protocol" | "unknown", retryAfterMs?: number}} ProviderHealth
+ * @typedef {{name: "codex" | "claude" | "kimi" | "opencode", executable: string, arguments: string[], parse: (record: unknown) => import("../types.js").WorkerEvent[], sessionId: (record: unknown) => string | undefined, health: (record: unknown) => ProviderHealth | undefined, completion?: (record: unknown) => boolean}} Provider
  */
 
 /** @type {readonly ["codex", "claude", "kimi", "opencode"]} */
@@ -16,19 +17,122 @@ export const PROVIDERS = ["codex", "claude", "kimi", "opencode"]
 export function createProvider(name, providerArguments, prompt, resumeSession, environment = process.env) {
   if (name === "codex") {
     const command = buildCodexCommand(providerArguments, prompt, resumeSession, environment)
-    return {...command, name: "codex", parse: parseCodexEvent, sessionId: codexSessionId}
+    return {...command, name: "codex", parse: parseCodexEvent, sessionId: codexSessionId, health: extractProviderHealth}
   }
   if (name === "claude") {
     const command = buildClaudeCommand(providerArguments, prompt, resumeSession, environment)
-    return {...command, name: "claude", parse: createClaudeParser(), sessionId: claudeSessionId}
+    return {...command, name: "claude", parse: createClaudeParser(), sessionId: claudeSessionId, health: extractProviderHealth}
   }
   if (name === "opencode") {
     const command = buildOpenCodeCommand(providerArguments, prompt, resumeSession, environment)
-    return {...command, name: "opencode", parse: createOpenCodeParser(), sessionId: createOpenCodeSessionId()}
+    return {...command, name: "opencode", parse: createOpenCodeParser(), sessionId: createOpenCodeSessionId(), health: extractProviderHealth}
   }
   if (name === "kimi") {
     const command = buildKimiCommand(providerArguments, prompt, resumeSession, environment)
-    return {...command, name: "kimi", parse: createKimiParser(), sessionId: createKimiSessionId(), completion: createKimiCompletion()}
+    return {...command, name: "kimi", parse: createKimiParser(), sessionId: createKimiSessionId(), completion: createKimiCompletion(), health: extractProviderHealth}
   }
   throw new Error(`--provider must be one of: ${PROVIDERS.join(", ")}`)
 }
+
+/**
+ * Extract safe provider health information from a structured provider record.
+ * Inspects only an explicit small list of safe containers — the top-level
+ * record and known nested `error`, `part`, `part.error`, or `*.data` objects —
+ * never traverses arbitrarily nested objects and never regexes raw message
+ * text. Generic HTTP 429 → retrying rate-limit. Structured
+ * exceeded_current_quota_error / insufficient_quota / insufficient_balance →
+ * blocked quota/billing. If no structured fields are exposed — common when a
+ * provider protocol suppresses upstream error details — no health fact is
+ * written and the run status remains running/unknown; Hermes must perform an
+ * independent bounded provider probe.
+ * @param {unknown} record
+ * @returns {ProviderHealth | undefined}
+ */
+export function extractProviderHealth(record) {
+  if (!isRecord(record)) return undefined
+
+  // Explicit containers to inspect: top-level record, record.error, record.part,
+  // record.part.error. Only these bounded paths; never recursive traversal.
+  const containers = [record]
+  if (isRecord(record.error)) containers.push(record.error)
+  if (isRecord(record.part)) {
+    containers.push(record.part)
+    if (isRecord(record.part.error)) containers.push(record.part.error)
+  }
+
+  for (const container of containers) {
+    const health = extractFromContainer(container)
+    if (health !== undefined) return health
+  }
+
+  return undefined
+}
+
+/**
+ * Inspect one safe container for structured health fields.
+ * @param {Record<string, unknown>} container
+ * @returns {ProviderHealth | undefined}
+ */
+function extractFromContainer(container) {
+  // Inspect structured data sub-object when present.
+  if (isRecord(container.data)) return extractFromContainer(container.data)
+
+  const httpStatus = container.http_status ?? container.httpStatus ?? container.status_code ?? container.statusCode
+  if (typeof httpStatus === "number" && Number.isSafeInteger(httpStatus)) {
+    if (httpStatus === 429) {
+      const retryAfterMs = safeRetryMs(container.retryAfterMs ?? container.retry_after_ms)
+      return {disposition: "retrying", category: "rate-limit", ...(retryAfterMs === undefined ? {} : {retryAfterMs})}
+    }
+    if (httpStatus >= 500 && httpStatus < 600) {
+      return {disposition: "retrying", category: "unknown"}
+    }
+  }
+
+  const code = container.code ?? container.error_code ?? container.errorCode ?? container.error_type ?? container.errorType
+  if (typeof code === "string") {
+    if (code === "exceeded_current_quota_error" || code === "insufficient_quota" || code === "quota_exceeded") {
+      return {disposition: "blocked", category: "quota"}
+    }
+    if (code === "insufficient_balance" || code === "billing_error" || code === "payment_required") {
+      return {disposition: "blocked", category: "billing"}
+    }
+    if (code === "invalid_api_key" || code === "unauthorized" || code === "auth_error" || code === "authentication_error") {
+      return {disposition: "blocked", category: "authentication"}
+    }
+    if (code === "forbidden" || code === "permission_denied") {
+      return {disposition: "blocked", category: "permission"}
+    }
+    if (code === "model_not_found" || code === "invalid_model" || code === "model_unavailable") {
+      return {disposition: "blocked", category: "model"}
+    }
+  }
+
+  if (container.insufficient_quota === true || container.quota_exceeded === true) {
+    return {disposition: "blocked", category: "quota"}
+  }
+  if (container.insufficient_balance === true) {
+    return {disposition: "blocked", category: "billing"}
+  }
+
+  return undefined
+}
+
+/**
+ * Extract a safe retry duration in milliseconds. Only explicit millisecond
+ * fields (retryAfterMs, retry_after_ms) are used; ambiguous short fields such
+ * as retry_after (seconds) are never interpreted as milliseconds.
+ * @param {unknown} value
+ */
+function safeRetryMs(value) {
+  if (typeof value === "number" && Number.isSafeInteger(value) && value > 0) return value
+  if (typeof value === "string" && /^\d+$/u.test(value)) {
+    const parsed = Number(value)
+    if (Number.isSafeInteger(parsed) && parsed > 0) return parsed
+  }
+  return undefined
+}
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}