threadwire 0.1.14 → 0.1.17

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 0.1.17 - 2026-08-06
+
+- Persist a normalized `provider_result` evidence artifact before final notification drain, separating it from quota-limited raw prompt/provider-stream evidence and separating `provider_completed`/`provider_failed` from authenticated `delivery_pending`/`delivery_succeeded`/`delivery_failed` state. Only durably finalized raw handles enter normalized results. Exhausted Telegram Retry-After/backoff attempts no longer rewrite provider success or discard its continuation/evidence handles, and ingress evidence-handle notices now use the existing bounded notice queue instead of an unbounded direct send. Isolated completion rejection and deadline cancellation now durably publish `provider_failed` with already observed assistant, continuation, and raw evidence before propagating the execution failure. Delivery transitions recover the exact sealed artifact redaction policy across restart, preserve its durable reservation, and record setup failures as `delivery_failed`. Add the token-free `file:<absolute-path>` target for private, fsynced, byte-identical normalized stdout capture without message delivery; result/transcript and activity paths now reject final symlink and parent-directory aliases before opening either output. Delivery failure records lack of a confirmed response, not exactly-once Telegram semantics after an ambiguous network failure.
+
+## 0.1.16 - 2026-08-04
+
+- Validate provider executable overrides at resolution time instead of deferring to spawn: `providerExecutable()` checks that a `THREADWIRE_*_BIN` override path exists, is executable (`X_OK`), and is a regular file (not a directory), falling back to the default with a diagnostic when the validation fails. This catches bogus overrides, stale temporary adapter paths, and directory targets before `runWorker` hits EACCES. The full test suite now uses real temporary executables instead of fake paths that relied on the old unchecked pass-through.
+
+## 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

@@ -1,6 +1,6 @@
 # Threadwire
 
-Threadwire is a Node.js CLI that launches a Codex, Claude, Kimi, or OpenCode worker and streams a concise, human-readable activity feed to one explicitly selected Telegram destination: a direct message, normal chat, or forum topic. The default feed includes the assistant's response prose, lifecycle outcomes, and diagnostics. Provider tool-status messages are disabled by default.
+Threadwire is a Node.js CLI that launches a Codex, Claude, Kimi, or OpenCode worker and either streams a concise, human-readable activity feed to one explicitly selected Telegram destination or writes a normalized result to an explicit local file target. The default Telegram feed includes the assistant's response prose, lifecycle outcomes, and diagnostics. Provider tool-status messages are disabled by default.
 
 For the container-native webhook deployment, including its named-volume worktree,
 non-root Codex provider, Docker secrets, loopback TLS proxy, verification, and
@@ -68,7 +68,7 @@ Use the local launcher. Install or refresh it after updating Threadwire with `np
   -- --model example-model
 ```
 
-The target always has the form `telegram:<chat-id>:<thread-id>` for topics, or `telegram:<chat-id>` for direct messages (DMs) and ordinary chats. The chat ID is always required and must be a nonzero signed integer. The thread ID is optional and valid only as the explicit topic suffix: when present it must be a positive safe integer, and a DM target simply omits it — a missing thread ID is never an error. `--provider` must be exactly one of `codex`, `claude`, `kimi`, or `opencode`. Malformed or missing provider, chat ID, or thread ID arguments are hard failures (exit code 2) reported through Threadwire's normal error path with fixed messages; they fail before the Telegram token is read, before any transport is created, and before any provider is launched, and the messages never echo the bot token or the untrusted argument value. `--process-number` accepts an explicit positive safe integer for automation; when omitted, Threadwire uses its launcher PID. Every Telegram message is labeled consistently, such as `[P42] …`, including chunked continuations.
+The target has the form `telegram:<chat-id>:<thread-id>` for topics, `telegram:<chat-id>` for direct messages (DMs) and ordinary chats, or `file:<absolute-path>` for local no-message execution. A file target requires a normalized absolute file path, needs no Telegram token, creates the file exclusively with mode `0600`, fsyncs it and its directory, and writes the exact same single normalized `delegated_result` record as stdout. It cannot be combined with `--transcript`. Telegram chat IDs and optional thread IDs keep their existing validation. `--provider` must be exactly one of `codex`, `claude`, `kimi`, or `opencode`. Malformed or missing provider or target arguments are hard failures (exit code 2) reported through Threadwire's normal error path before any provider is launched. `--process-number` accepts an explicit positive safe integer for automation; when omitted, Threadwire uses its launcher PID. Every Telegram message is labeled consistently, such as `[P42] …`, including chunked continuations.
 
 `--cwd` is the complete workspace contract for every provider. It may name any caller-accessible directory, including a non-Git directory. Threadwire passes it unchanged to the native provider and performs no profile, repository, source-identity, task-binding, or root-allowlist lookup. `--workspace-profile` has been removed and is rejected; migrate invocations by replacing it with `--cwd <directory>`.
 
@@ -84,15 +84,17 @@ The relay contract: the caller supplies `THREADWIRE_TARGET` (`telegram:<chat-id>
 
 Pass `--resume-session <exact-provider-session-id>` to continue a stored Codex, Claude, Kimi, or OpenCode session. Threadwire preserves the provider's native resume ordering and streaming options and never uses implicit latest-session behavior.
 
-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.
+Pass `--transcript <path>` with a Telegram target 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. A `file:<absolute-path>` target provides this capture directly and therefore rejects a separate `--transcript`. Neither form contains provider JSONL, reasoning, tool payloads, prompts, stderr, or credentials. The result/transcript path and `--activity-log` path must not canonically alias; final-component symlinks and aliased parent directories are rejected during preflight before either output is opened.
 
-`--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.
 
 For normal `threadwire run` execution, Threadwire stdout is the parent-model admission plane. It emits exactly one versioned terminal `delegated_result` JSON object and no progress records. The envelope contains a bounded, credential-redacted, control-normalized final conclusion when one was produced, structured terminal state and exit code, and the exact bounded provider session handle when available. Its closed schema can also represent concise blocker/decision requests, opaque artifact handles, commit/URL references, and a concise validation summary; current provider adapters do not infer these optional fields from prose. Unknown, nested, wrongly typed, cardinality-invalid, or oversized admission candidates fail closed. See [Delegated-result protocol](docs/delegated-result-protocol.md) for the complete schema, limits, and caller obligations.
 
-Scoped raw evidence artifacts are separate from both files above. Set the trusted operator setting `THREADWIRE_EVIDENCE_ROOT` for standalone runs to persist the delegated prompt and raw provider stdout/stderr as a scoped file-backed artifact; Telegram ingress uses its dedicated evidence volume automatically. The parent or owning Telegram topic receives only an opaque bearer handle. Retrieve later with `threadwire evidence read` or the authenticated `/evidence` Telegram command and an explicit bounded selector. See [Evidence artifacts](docs/evidence-artifacts.md) for permissions, quotas, retention, recovery, authorization, redaction, privacy, and cleanup behavior.
+Scoped evidence artifacts are separate from both files above. Set the trusted operator setting `THREADWIRE_EVIDENCE_ROOT` for standalone runs; Telegram ingress uses its dedicated evidence volume automatically. CLI and ingress runs reserve separate normalized provider-result and raw prompt/provider-stream artifacts; CLI raw evidence also records final context metrics. A raw handle enters a normalized result only after the raw artifact is durable; if raw metrics append or finalization fails, the error remains visible while the completed provider result retains only its independently durable result handle. The result artifact carries a stable delivery identity and authenticated state, and ingress sends that result handle through the same bounded notice queue. Retrieve later with `threadwire evidence read` or the authenticated `/evidence` Telegram command and an explicit bounded selector. See [Evidence artifacts](docs/evidence-artifacts.md) for permissions, delivery states, quotas, retention, recovery, authorization, redaction, privacy, and cleanup behavior.
 
 `threadwire capacity` is a read-only reporting command that probes live account capacity for authenticated Codex (`codex app-server` JSON-RPC `account/rateLimits/read`) and Kimi (`GET https://api.kimi.com/coding/v1/usages` with the installed OAuth credential), normalizes both into one closed short/long-window schema, and prints one deterministic reserve-gated admission selection as a single JSON document. It persists nothing, never prints tokens or account data, takes no session arguments, and does not change `run` provider selection; an external worker ledger consumes the report and owns pinning provider/model/session. See [Capacity admission](docs/capacity-admission.md) for the schema, tie-break, error taxonomy, and security boundary.
 
@@ -102,9 +104,9 @@ The Telegram bot token is used only by Threadwire's notifier and both `TELEGRAM_
 
 A single trusted renderer is the only code allowed to enqueue Telegram notices. By default, parsed assistant text is forwarded in order with every nonblank rendered line labeled `[P<n>] Assistant: `; no CLI flag is required. This preserves Markdown, code-block indentation, blank lines, and whitespace attached to nonblank content while preventing assistant text from imitating trusted activity on a later line. Streamed fenced JavaScript blocks (` ```js ` / ` ```javascript `) are instead emitted as independently valid, escaped Telegram HTML code messages: the `[P<n>] Assistant:` label stays above the code block, and long blocks are Unicode-safe chunked without exposing raw fences. A short blank-only stream is suppressed at normal close. Because retention is bounded, a blank-only prefix longer than the buffer limit is emitted in oldest-first chunks while at most one limit's worth remains deferred; a later visible assistant character therefore still reconstructs the input exactly, but an indefinitely blank stream cannot be suppressed indefinitely. With `--tool-messages`, tool activity uses a single edit-in-place status line (silent `🛠 …` on start, edited to begin `✅` on finish); without it, both the send and completion edit are suppressed. Worker start/completion/failure and warning/error diagnostics continue to use fixed labeled templates in either mode. Non-assistant provider fields—including summaries, tool names, metadata IDs, inputs, commands, stderr content, raw JSON, reasoning/thinking, tokens, and retry internals—are not forwarded. When tool messages are enabled, the sole provider-data exception is normalized Codex command-completion output: it is appended only to its original tool status edit as an escaped, bounded, expandable Telegram HTML blockquote after shared credential redaction.
 
-Assistant deltas from all provider stream IDs share one ordered sentence-boundary buffer, preserving provider-event order. The buffer has a finite 16,384-character default: a continuously active punctuation-free stream emits and clears Unicode-safe fixed-size chunks instead of growing indefinitely. Structured events flush any earlier assistant tail, including retained leading whitespace, before their own fixed notice. Completed boundaries enter delivery without a deliberate batching delay; messages combine only when already naturally queued behind delivery. When Telegram briefly falls behind, Threadwire emits a fixed safe notice that the notifier saturated and then coalesces only eligible assistant progress until headroom returns; lifecycle, diagnostics, and tool activity remain ordered and non-droppable. Notices remain ordered, size-limited, paced, and retried conservatively when Telegram reports throttling or a transient failure.
+Assistant deltas from all provider stream IDs share one ordered sentence-boundary buffer, preserving provider-event order. The buffer has a finite 16,384-character default: a continuously active punctuation-free stream emits and clears Unicode-safe fixed-size chunks instead of growing indefinitely. Structured events flush any earlier assistant tail, including retained leading whitespace, before their own fixed notice. Completed boundaries enter delivery without a deliberate batching delay; messages combine only when already naturally queued behind delivery. When Telegram briefly falls behind, Threadwire emits a fixed safe notice that the notifier saturated and then coalesces only eligible assistant progress until headroom returns; lifecycle, diagnostics, and tool activity remain ordered and non-droppable. Notices remain ordered, size-limited, paced, and retried conservatively when Telegram reports throttling or a transient failure. A provider result is admitted independently: exhausted delivery retries return a delivery failure without rerunning the provider or changing its completed normalized result.
 
-The delivery queue has finite defaults of 100 pending notices and 256 KiB of pending UTF-8 text. Message length and capacity settings require positive safe integers; pacing settings require nonnegative safe integers. A notice larger than the byte limit or a limit-plus-one enqueue latches a terminal capacity error, discards queued (not already in-flight) notices, and rejects every later enqueue. Unicode chunks never split a surrogate pair, and every labeled continuation retains its complete process label. If the label cannot fit with content under a configured message length, delivery latches a terminal chunking error before sending. These rules make delivery loss visible and prevent slow or rate-limited transports from consuming unbounded memory.
+The delivery queue has finite defaults of 100 pending notices and 256 KiB of pending UTF-8 text. Message length and capacity settings require positive safe integers; pacing settings require nonnegative safe integers. A notice larger than the byte limit or a limit-plus-one enqueue latches a terminal capacity error, discards queued (not already in-flight) notices, and rejects every later enqueue. Unicode chunks never split a surrogate pair, and every labeled continuation retains its complete process label. If the label cannot fit with content under a configured message length, delivery latches a terminal chunking error before sending. These rules make delivery loss visible and prevent slow or rate-limited transports from consuming unbounded memory. A persisted `delivery_failed` state means Threadwire received no successful response after the bounded attempts. A timeout or dropped response can be ambiguous, so Threadwire guarantees provider non-rerun but does not claim exactly-once Telegram display.
 
 ## Development
 

package/docs/delegated-result-protocol.md

@@ -7,6 +7,10 @@ Threadwire has two deliberately separate output planes:
 - Standard output for a normal `threadwire run` is the parent-model admission
   plane. It contains exactly one newline-terminated terminal JSON envelope.
 
+`--target file:<absolute-path>` disables message delivery and durably writes the
+same admission record to that private, exclusive file before stdout. It requires
+no Telegram token and cannot be combined with `--transcript`.
+
 Standard error remains a caller diagnostic channel and is never admission
 content. Provider stdout is private parser input.
 
@@ -108,6 +112,22 @@ references exactly. Streamed conclusion collection is credential-redacted,
 control-normalized, and deterministically truncated with a final ellipsis when
 necessary. Code-point accounting never splits a UTF-16 surrogate pair.
 
+Provider and delivery outcomes are independent. When evidence is enabled, the
+first artifact handle identifies a normalized `provider_result` containing the
+terminal envelope and final assistant content. That artifact is atomically
+published before final notification drain and records a stable delivery
+identity/state. Any separate raw-evidence handle is admitted only after that
+artifact is durable, so a late raw quota or finalization failure cannot leave a
+stale recovery capability in either result. A provider exit zero remains
+`completed` even when the process returns exit 2 because notification delivery
+exhausted its bounded retries.
+An isolated completion rejection or deadline still publishes `provider_failed`
+with assistant content, continuation, and durable raw evidence observed before
+the failure, then propagates the execution error after bounded cancellation and
+cleanup settlement. Any cleanup or delivery failure remains attached without
+masking that primary execution failure.
+The continuation and evidence handles remain admitted for recovery.
+
 A continuation handle consists of one or more colon-separated opaque segments.
 Each segment must start with an ASCII letter or digit and may then contain only
 ASCII letters, digits, `_`, `-`, and `.`. This covers provider UUIDs, token IDs

package/docs/evidence-artifacts.md

@@ -6,11 +6,24 @@ parent admission stream. Telegram uses the dedicated
 with the trusted operator setting `THREADWIRE_EVIDENCE_ROOT`; callers cannot
 select a root through CLI arguments.
 
-The store records the prompt and framed provider stdout/stderr events, including
-tool calls, commands, raw results, and intermediate narration the provider
-emits. Threadwire stdout still contains one bounded `delegated_result`; evidence
-adds only an unguessable bearer handle. Storage failure fails the run explicitly
-and never falls back to inlining evidence.
+For CLI and Telegram ingress runs, the store publishes a small normalized
+result artifact separately from the prompt and framed provider stdout/stderr
+artifact. The result contains one closed `provider_result` record with `provider_completed` or
+`provider_failed`, the bounded final assistant content, the exact continuation,
+and the terminal `delegated_result`. It is fsynced and atomically published
+before final notification drain. A raw handle is admitted only after its
+artifact is also durable; raw quota or finalization failure is surfaced without
+invalidating the normalized result handle. The raw artifact still contains tool
+calls, commands, raw results, and intermediate narration. CLI raw evidence also
+ends with the final context metrics.
+An isolated completion rejection or deadline first awaits bounded runtime
+cancellation and cleanup settlement, then publishes `provider_failed` with
+assistant content, continuation, and raw evidence observed before the failure
+before propagating the execution error. Cleanup or delivery failures remain
+attached to that primary execution failure.
+Threadwire stdout remains one bounded `delegated_result`; evidence adds only
+unguessable bearer handles. Storage failure fails explicitly and never falls
+back to inlining evidence.
 
 ## Security and lifecycle
 
@@ -39,6 +52,25 @@ while active. Fsync and atomic rename publish payload before ready metadata.
 Startup removes partial/corrupt states and rehydrates only exact-schema,
 unexpired ready artifacts.
 
+Result metadata additionally authenticates one stable delivery identity and a
+closed state: `delivery_pending`, `delivery_succeeded`, `delivery_failed`, or
+`delivery_not_requested`. The pending record is part of the initial atomic
+publication. After the existing bounded notice queue settles, Threadwire
+atomically replaces ready metadata and re-seals its redaction-policy AAD with
+the terminal delivery state. The transition decrypts the exact artifact policy
+from ready metadata rather than reconstructing it from runtime configuration or
+an in-memory cache, preserving duplicate and artifact-specific redactions and
+its durable reservation across restart. Retrieval returns this state with
+result-artifact content; legacy artifacts without delivery metadata remain
+readable.
+
+`delivery_failed` means no successful transport response was confirmed,
+including when notifier setup fails or the queue exhausts its bounded
+Retry-After/backoff attempts. It does not prove that a
+timed-out or response-lost Telegram request was not displayed. Recovery retries
+must use the persisted provider result and must never rerun the provider;
+Threadwire does not claim exactly-once Telegram send semantics.
+
 Defaults are 1 MiB/event; 64 MiB and 100,000 events/artifact; 128 MiB and
 200,000 events/run; 1 GiB, 1,000,000 events, and 10,000 artifacts/store;
 seven-day retention; and a 64 KiB/1,000-line serialized-response ceiling.

package/package.json

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

package/scripts/install-local-launcher.js

@@ -52,6 +52,28 @@ if [[ "$threadwire_validation_status" -ne 0 ]]; then
   exit "$threadwire_validation_status"
 fi
 
+threadwire_arguments=("$@")
+threadwire_target=""
+shift
+while [[ "$#" -gt 0 ]]; do
+  case "$1" in
+    --) break ;;
+    --tool-messages|--relay-write) shift ;;
+    --target)
+      threadwire_target="$2"
+      shift 2
+      ;;
+    *)
+      if [[ "$#" -lt 2 ]]; then break; fi
+      shift 2
+      ;;
+  esac
+done
+
+if [[ "$threadwire_target" == file:* ]]; then
+  exec node "$THREADWIRE_ENTRYPOINT" "\${threadwire_arguments[@]}"
+fi
+
 if [[ ! -r "$THREADWIRE_DOTENV_PATH" ]]; then
   printf 'threadwire: required dotenv is not readable: %s\\n' "$THREADWIRE_DOTENV_PATH" >&2
   exit 2
@@ -77,7 +99,7 @@ if [[ -z "$telegram_bot_token" ]]; then
 fi
 
 export THREADWIRE_TELEGRAM_BOT_TOKEN="$telegram_bot_token"
-exec node "$THREADWIRE_ENTRYPOINT" "$@"
+exec node "$THREADWIRE_ENTRYPOINT" "\${threadwire_arguments[@]}"
 `
 }
 

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)
+}