threadwire 0.1.13 → 0.1.15

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## 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.
+
+## 0.1.14 - 2026-08-03
+
+- Fix native Kimi runs hanging after a successful response: terminal completion is now explicit and provider-owned instead of derived only from process exit. Kimi's parser confirms completion from its stream-json protocol — a final assistant response (assistant content without further tool calls) plus the `session.resume_hint` handoff, in either order — and once confirmed, Threadwire preserves the session continuation handle, terminates the attempt-owned provider process group (`SIGTERM`), and emits exactly one `delegated_result`. Success settles only once the entire owned group is gone: a member that survives `SIGTERM` — including an attempt-owned grandchild after the direct provider exits — keeps the grace-period escalation running and receives `SIGKILL` against the exact group (liveness is probed with signal 0 against the group, never name matching or broad scans) before settlement, so no descendant leaks. Normal exit semantics are unchanged: a provider that exits nonzero before protocol completion remains a failure, and long-running tool activity stays unbounded with no generic idle timeout. Cancellation, consumer/relay failure, and launch failure clean up the complete attempt-owned process tree through the detached process group: parent `SIGINT`/`SIGTERM` cancellation now owns grace-period escalation (surviving members are `SIGKILL`ed against the exact group) and settles with the forwarded signal's exit status (never protocol success), and a consumer failure that lands after the direct child closed probes the exact group and terminates/escalates surviving descendants before rejecting the original error. `runWorker` also accepts an explicit `AbortSignal` (wired from the caller launch deadline where one exists): an abort terminates the exact owned group with the same grace/escalation and settles with the abort failure, never success. Settlement after any `SIGKILL` now waits for bounded cleanup confirmation — the exact process group is re-probed (or, where no process group exists such as win32, the direct child's own close is required) before success, failure, or cancellation settles; if owned processes cannot be confirmed gone within the bounded window (`cleanupConfirmationMs`, default 5s), the run settles as a cleanup failure, never success, preserving the original failure or cancellation context. Once the provider protocol confirms completion, the current stdout chunk stops draining immediately so trailing records can never produce duplicate output or consumer failures.
+- Add a checked-in development container: the `app` service in `compose.dev.yaml` builds `docker/Dockerfile.dev` (Ubuntu 26.04 pinned by registry-verified digest, stable non-root `dev` user `1000:1000`, Node 22 LTS from the official SHA-256-verified tarball, distro GitHub CLI, and the npm-latest Codex/Claude/Kimi/OpenCode CLI baseline with Threadwire resolved through unversioned `npx threadwire`). The complete `DEV_HOME_PATH` home is bind-mounted at `/home/dev` with the checkout at `/home/dev/threadwire`, the host GitHub CLI config mounts read-only at `/home/dev/.config/gh` from the required `GH_CONFIG_SOURCE_PATH`, and an immutable agent-context snapshot mounts read-only at `/opt/agent-context` from the required `AGENT_CONTEXT_PATH`; the entrypoint proves the auth mount is read-only, initializes the HTTPS Git credential helper in the writable home, and links the context's AGENTS/CLAUDE guidance and trusted skills into every installed worker's discovery home (`.claude`, `.codex`, `.config/opencode`, `.kimi-code`). A one-shot `home-init` service precreates the provider parent directories as `1000:1000` on blank homes so Docker never creates the nested auth mount's parent root-owned. Project guidance and validation commands are documented in the new `AGENTS.md`. Production runtime files are unchanged.
+- Add the read-only `threadwire capacity` command: it probes live account capacity for authenticated Codex (a bounded `codex app-server` JSON-RPC `initialize` + `account/rateLimits/read` exchange resolved like the Codex worker provider) and Kimi (`GET https://api.kimi.com/coding/v1/usages` with the OAuth bearer read through the hardened credential store's non-mutating `getCurrentAccessToken` — never refreshed, persisted, or tombstoned; a credential inside the 30-second validity margin classifies as `unavailable`), normalizes both into one closed short/long-window schema (`usedPercent`/`remainingPercent`/`resetAt`/duration, floored remaining percent, fail-closed exact-keys validation), and prints exactly one JSON report with per-provider `ok`/`unavailable`/`auth`/`protocol` statuses and a single deterministic admission selection. Selection rejects candidates below configurable short/long reserves (defaults 20%/10%), scores survivors by their most constrained window (absent long window non-constraining), and breaks ties by long-window remaining then provider name, so identical snapshots always reproduce the identical selection; no survivor yields `selection: null` and exit code 2. Tokens, raw credentials, account and plan data, and server error detail never enter output, errors, fixtures, or logs; the command writes nothing to disk, takes no session arguments, and leaves `run`, `evidence`, ingress, brokers, and the isolated runtime byte-identical. Provider/model/session pinning for tasks remains with the external worker ledger; see `docs/capacity-admission.md`.
+
 ## 0.1.13 - 2026-08-01
 
 - Remove the default one-hour full-run deadline from the isolated runtime: when `THREADWIRE_ISOLATED_RUNTIME_CLIENT_TIMEOUT_MS` (client) and `THREADWIRE_WORKER_TIMEOUT_MS` (supervisor) are unset or blank, a healthy running worker continues until natural completion, caller cancellation/disconnect, supervisor shutdown, or concrete failure. Setting either to a positive millisecond value enables the existing single absolute preflight+run deadline with unchanged validation and caps. Compose no longer inserts numeric timeout defaults. Preflight admission, per-operation Docker/network calls, state collection (30 seconds), and emergency cleanup stay independently bounded.

package/README.md

@@ -74,7 +74,7 @@ The target always has the form `telegram:<chat-id>:<thread-id>` for topics, or `
 
 Provider tool-start and tool-finish events do not produce Telegram messages by default. Pass the boolean `--tool-messages` flag to opt in, as shown above. When enabled, each tool is one concise, silent status line rather than a pair of noisy start/finish notices: when a tool starts, Threadwire sends `🛠 [P42] Tool: <safe command or tool description>` (for example `🛠 [P42] Tool: command — git status --short`), and when that same tool finishes, it edits the original message in place so it begins `✅` instead — no second completion message is sent, and Telegram edits raise no notification. The command/description shows a safe CLI-style preview with credential-bearing values (tokens, passwords, keys, authorization/cookie forms, credentials in URLs) redacted and control characters stripped; only normalized Codex command-completion output may also be appended to that same edited status as a Telegram-native expandable HTML blockquote with the visible label `Output →`; it is credential-redacted, HTML-escaped, and Unicode-safe bounded. Stderr, reasoning, and every other raw provider result remain excluded. Use `--max-output-length <positive-integer>` to truncate only that preview Unicode-safely; omit the option for unlimited tool detail. A prompt may instead come from `--prompt-file` or piped stdin, and every source rejects blank/whitespace content. Arguments following `--` pass to the selected provider, except output-stream and session options owned by Threadwire. Native Kimi uses the caller's compatible configuration. Threadwire maps its public `--resume-session <exact-id>` option to Kimi's native `--session <exact-id>` option and owns `--prompt` plus `--output-format stream-json`. The caller environment or image must provide the Kimi executable at `/usr/local/bin/kimi` or set `THREADWIRE_KIMI_BIN`; a missing executable fails normally.
 
-Threadwire directly spawns the structurally separate terminal adapters `/opt/data/libexec/threadwire/codex`, `/opt/data/libexec/threadwire/claude`, `/usr/local/bin/kimi`, or `/opt/data/libexec/threadwire/opencode-local-fleet` with an argv array and `shell: false`. These libexec adapters hold the real provider-CLI logic and are never on a worker's `PATH`, so relaying can never recurse back into the front-door shims. Each spawn also sets `THREADWIRE_ACTIVE=1` in the provider child environment. The executable can be overridden per provider with `THREADWIRE_CODEX_BIN`, `THREADWIRE_CLAUDE_BIN`, `THREADWIRE_KIMI_BIN`, or `THREADWIRE_OPENCODE_BIN` for staged cutover and rollback. It does not impose a worker timeout. `SIGINT` and `SIGTERM` are forwarded to the worker as explicit cancellation.
+Threadwire directly spawns the structurally separate terminal adapters `/opt/data/libexec/threadwire/codex`, `/opt/data/libexec/threadwire/claude`, `/usr/local/bin/kimi`, or `/opt/data/libexec/threadwire/opencode-local-fleet` with an argv array and `shell: false`. These libexec adapters hold the real provider-CLI logic and are never on a worker's `PATH`, so relaying can never recurse back into the front-door shims. Each spawn also sets `THREADWIRE_ACTIVE=1` in the provider child environment. The executable can be overridden per provider with `THREADWIRE_CODEX_BIN`, `THREADWIRE_CLAUDE_BIN`, `THREADWIRE_KIMI_BIN`, or `THREADWIRE_OPENCODE_BIN` for staged cutover and rollback. It does not impose a worker timeout. `SIGINT` and `SIGTERM` are forwarded to the worker as explicit cancellation. Terminal completion is explicit and provider-owned rather than derived only from process exit: native Kimi confirms a completed run with a final assistant response (assistant content without further tool calls) plus its session handoff record in the stream. Once both records are confirmed, Threadwire preserves the session continuation handle, terminates the attempt-owned provider process group (`SIGTERM`), and emits exactly one `delegated_result`. Success settles only once the entire owned group is gone: members that survive `SIGTERM` — including attempt-owned grandchildren — keep the grace-period escalation running and receive `SIGKILL` against the exact group before settlement, so no descendant is leaked even when the direct provider exits first. A provider that exits nonzero before its protocol confirms completion keeps its failure status, and long-running tool activity remains unbounded: there is no generic idle timeout, only caller cancellation or an explicit deadline. Parent `SIGINT`/`SIGTERM` is owned cancellation, not just forwarding: the signal reaches the exact attempt-owned group, surviving members are escalated to `SIGKILL` after the grace period, and settlement keeps the forwarded signal's exit status (143/130 on Linux) only after the owned tree is gone. Relay/consumer failure cleans up the same owned tree — even when the failure lands after the direct child closed and only descendants survive — and the worker runner also accepts an explicit `AbortSignal`: an abort terminates the exact attempt-owned group with the same grace/escalation and settles with the abort failure, never success. After any `SIGKILL`, settlement waits for bounded cleanup confirmation — the exact group is re-probed, or on platforms without process groups the direct child's close is required — and cleanup that cannot be confirmed within the bounded window settles as failure, never success; this confirmation bound is not an idle or tool-activity timeout.
 
 ## Provider front-door shims
 
@@ -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.
 
@@ -94,6 +96,8 @@ For normal `threadwire run` execution, Threadwire stdout is the parent-model adm
 
 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.
 
+`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.
+
 Telegram is the separate user-visible progress plane. Lifecycle notices, diagnostics, tool activity, and assistant streaming continue there independently; `--tool-messages` affects only Telegram. Execution-environment details, provider records and streams, lifecycle progress, diagnostics, tool names/arguments/details/output, stderr, prompts, narration/reasoning, and full transcripts never enter stdout. Threadwire's bounded error diagnostic remains on stderr. Help output is the sole non-run, human-readable stdout mode. This default is an intentional pre-1.0 protocol break from the former mixed Hermes JSONL stream.
 
 The Telegram bot token is used only by Threadwire's notifier and both `TELEGRAM_BOT_TOKEN` and `THREADWIRE_TELEGRAM_BOT_TOKEN` are removed from every provider child environment. The three libexec adapters repeat that scrub as defense in depth. Other environment variables, including the providers' own authentication and normal process configuration, are preserved. Outbound Telegram fetch and response-body parsing share a 30-second deadline by default; set `THREADWIRE_TELEGRAM_REQUEST_TIMEOUT_MS` to a positive safe integer no greater than `2147483647` to override it.
@@ -106,6 +110,11 @@ The delivery queue has finite defaults of 100 pending notices and 256 KiB of pen
 
 ## Development
 
+The checked-in development container is the `app` service in `compose.dev.yaml`
+(Ubuntu 26.04 pinned by digest, non-root `1000:1000`, Node 22 LTS, npm-latest
+coding CLI baseline). Setup, the read-only GitHub CLI and agent-context mount
+contracts, and container commands are documented in [AGENTS.md](AGENTS.md).
+
 Tests use synthetic provider records, a local fixture child, and injected transports. They never invoke Codex, Claude, or Telegram.
 
 ```sh

package/docs/capacity-admission.md

@@ -0,0 +1,147 @@
+# Capacity admission
+
+`threadwire capacity` probes live account capacity for the authenticated Codex
+and Kimi providers, normalizes both into one closed schema, and makes a single
+deterministic admission selection. It is a read-only reporting command: it
+writes nothing to disk, changes no provider or runtime state, and never
+launches, resumes, or selects a session. An external worker ledger consumes
+the report and owns pinning the selected provider, model, and native session
+across planning, implementation, debugging, and corrections; Threadwire
+deliberately has no task-ledger ownership, no `--provider auto`, and no
+capacity-based selection inside `threadwire run`.
+
+## Command
+
+```
+threadwire capacity [--provider <codex|kimi>]...
+                    [--short-reserve-percent <0-100>]   # default 20
+                    [--long-reserve-percent <0-100>]    # default 10
+                    [--timeout-ms <positive-integer>]   # default 15000
+```
+
+Stdout carries exactly one JSON document:
+
+```json
+{
+  "version": 1,
+  "generatedAt": "2026-08-02T00:00:00.000Z",
+  "reserves": {"shortPercent": 20, "longPercent": 10},
+  "candidates": [
+    {
+      "provider": "codex",
+      "status": "ok",
+      "windows": {
+        "short": {"usedPercent": 40, "remainingPercent": 60, "resetAt": "2026-08-02T00:00:00.000Z", "windowDurationSeconds": 18000},
+        "long": {"usedPercent": 10, "remainingPercent": 90, "resetAt": "2026-08-09T00:00:00.000Z", "windowDurationSeconds": 604800}
+      }
+    }
+  ],
+  "rejected": [{"provider": "kimi", "reason": "auth"}],
+  "selection": {"provider": "codex", "score": 60}
+}
+```
+
+Exit code is `0` when `selection` is non-null and `2` for invalid arguments or
+when no candidate survives; the report is still printed in the latter case.
+`generatedAt` is the only wall-clock field: the same `candidates` and
+`reserves` always reproduce the same `selection`, so the caller can re-verify a
+pin before relying on it.
+
+## Probes and normalization
+
+- **Codex** spawns `codex app-server` and runs a bounded two-request JSON-RPC
+  exchange over stdio: `initialize`, then `account/rateLimits/read`. The
+  executable resolves via `THREADWIRE_CODEX_BIN` or the default libexec
+  adapter, exactly like the Codex worker provider; the anti-recursion default
+  is unchanged, so native container callers point the existing safe override
+  at the real CLI (for example `THREADWIRE_CODEX_BIN=/usr/local/bin/codex`).
+  Only the quota projection of the result is parsed: `rateLimits.primary` maps
+  to `short` and `rateLimits.secondary` to `long`; a `null` secondary yields a
+  short-only snapshot, and a secondary shorter than the primary fails closed.
+  Each window requires exactly `usedPercent`, `windowDurationMins`, and
+  `resetsAt` (epoch seconds, normalized to the canonical `resetAt` output
+  field); missing, obsolete, or extra keys fail closed, and unrelated result
+  or `rateLimits` metadata is neither read nor propagated.
+- **Kimi** calls `GET https://api.kimi.com/coding/v1/usages` with the OAuth
+  bearer from the installed Kimi credential store, loaded through the same
+  hardened store as the model broker. The credential file resolves in order: a
+  non-empty absolute `THREADWIRE_KIMI_OAUTH_FILE` override, then the installed
+  CLI's canonical `${KIMI_CODE_HOME}/credentials/kimi-code.json`, then the
+  vendor default `${HOME}/.kimi-code/credentials/kimi-code.json`; missing,
+  relative, or NUL-containing candidates never qualify and resolution fails
+  closed as `auth` without logging any path. Only the quota projection of the
+  response is parsed: top-level `usage` is the long account quota (documented
+  weekly duration of 604,800 seconds) and the shortest `limits[]` window maps
+  to `short`; every returned window is validated (`window.duration` in
+  `TIME_UNIT_MINUTE`s, `detail` quota) but intermediate windows are ignored,
+  and normalization fails closed if the long duration would not exceed the
+  short. Quota fields are strict non-negative decimal strings validated with
+  `used + remaining === limit` and a positive limit, reset times must be
+  bounded ISO-8601, and remaining percent is floored so normalization never
+  overstates capacity. Unrelated top-level response fields are neither read
+  nor propagated into output or errors.
+
+Both probes are bounded (capped lines/bytes, single absolute timeout) and fail
+closed on any shape drift: exact keys within the parsed projection, forced
+types, `0–100` percents, positive bounded durations, and reset times
+normalized to ISO-8601 UTC.
+
+## Selection semantics
+
+`selectProvider` is pure (no I/O, no clock):
+
+1. Candidates whose `status` is not `ok` are rejected with their status as the
+   reason (`unavailable`, `auth`, or `protocol`).
+2. A candidate is rejected with `short-reserve` when its short-window
+   `remainingPercent` is below `shortPercent`, and with `long-reserve` when a
+   present long window is below `longPercent`. An absent long window is
+   non-constraining. A remaining percent equal to the reserve passes.
+3. Survivors are scored by their most constrained window:
+   `min(shortRemaining, longRemaining)` with an absent long window counting as
+   100.
+4. Ordering is total and deterministic: score descending, then long-window
+   remaining descending, then provider name ascending (`codex` before `kimi`).
+5. No survivor yields `selection: null` and exit code `2`.
+
+## Error taxonomy
+
+Per provider, independently of the other:
+
+- `ok` — a normalized snapshot was produced.
+- `unavailable` — transport failure, timeout, spawn failure, early child exit,
+  5xx, or OAuth refresh unavailability.
+- `auth` — 401/403, logged-out (tombstone) Kimi credentials, missing Kimi
+  credential configuration, or a Codex server-side authentication rejection.
+- `protocol` — malformed JSON, wrong content type, JSON-RPC error, out-of-order
+  exchange, or any response shape drift.
+
+## Security boundary
+
+- Tokens and raw credentials are used in-process only and are never printed,
+  persisted, or embedded in errors. The Kimi bearer is read through
+  `openKimiOAuthStore`'s non-mutating `getCurrentAccessToken` (returned only
+  while valid beyond a fixed 30-second safety margin): the probe never
+  refreshes, persists, renames, or tombstones credentials, and a credential
+  inside the margin classifies as `unavailable` with a fixed message. Probe
+  failures use the store's fixed-message discipline with no causes. Codex
+  server error detail (which can carry account material) is inspected for
+  classification only and never propagated.
+- The report schema is closed and carries only provider names, statuses, fixed
+  messages, and window numbers — no account IDs, plan names, emails, tokens, or
+  raw response bodies. Committed test fixtures contain sanitized structure with
+  representative numeric values only.
+- The Codex child is always killed (success, error, and timeout), its stderr is
+  consumed but never forwarded, and the exchange is bounded. Kimi requests use
+  `redirect: "error"`, strict JSON content-type, and a capped body read.
+- The command introduces no new environment variables and no persistence, so
+  the existing evidence redaction sweep is unaffected.
+
+## Ledger contract
+
+The external worker ledger calls `threadwire capacity`, verifies the report,
+and pins the selected provider, the model (from its own allowlists — capacity
+is account-level and Threadwire performs no model selection), and the native
+session for the task. Resumed sessions and correction runs reuse that pin and
+must not re-run admission; `threadwire capacity` takes no session arguments and
+`threadwire run` explicit-provider and `--resume-session` behavior is
+unchanged.

package/docs/development-container.md

@@ -0,0 +1,77 @@
+# Development container
+
+`compose.dev.yaml` provides the persistent `app` service for Threadwire
+development. It is separate from the production runtime definitions. The image
+installs Codex CLI, Claude Code CLI, the official Kimi Code CLI, OpenCode,
+`oc-codex-multi-auth`, `@ai-sdk/openai-compatible`, and `@ai-sdk/xai` during the
+Docker build. Runtime setup never downloads a plugin through `npx`.
+
+## Source paths
+
+All source paths in `.env` are required and have no checked-in host defaults:
+
+- `DEV_HOME_PATH` is the complete dedicated development home. It remains the
+  owner of OpenCode database, session, log, and cache state.
+- `GH_CONFIG_SOURCE_PATH` is the GitHub CLI config directory and mounts
+  read-only.
+- `CODEX_AUTH_SOURCE_PATH` is native Codex's `auth.json` and mounts read-write
+  so OAuth refreshes persist to its canonical owner.
+- `OPENCODE_AUTH_SOURCE_PATH` is OpenCode's native `auth.json`. DeepSeek, xAI,
+  and Moonshot AI keys are entered with OpenCode's auth flow and persist
+  through this read-write file mount.
+- `OPENCODE_CODEX_STATE_SOURCE_PATH` is the plugin's dedicated state directory,
+  containing the OpenAI OAuth file and global account pool. It mounts
+  read-write as a directory because pool updates use atomic sibling-file
+  replacement.
+- `AGENT_CONTEXT_PATH` is the immutable agent-context snapshot and mounts
+  read-only.
+
+Hermes owns the canonical credential files. Do not copy them into the checkout,
+the image, or project-keyed task-home files. The app sets
+`CODEX_AUTH_PER_PROJECT_ACCOUNTS=0`, so `oc-codex-multi-auth` uses its one
+global mounted account pool rather than creating per-project credential copies.
+
+## OpenCode catalog
+
+The image-owned `/usr/local/share/threadwire-dev/opencode.json` is root-owned,
+read-only, secret-free, and selected with OpenCode's supported
+`OPENCODE_CONFIG` mechanism. It exposes:
+
+- OpenAI OAuth through `oc-codex-multi-auth`: `gpt-5.6-sol`,
+  `gpt-5.6-terra`, and `gpt-5.6-luna`.
+- DeepSeek through `@ai-sdk/openai-compatible` at
+  `https://api.deepseek.com/v1`: `deepseek-v4-pro` and
+  `deepseek-v4-flash`.
+- xAI through `@ai-sdk/xai`: `grok-4.5`, `grok-build-0.1`, and
+  `grok-code-fast-1`.
+- Kimi K3 through OpenCode's built-in `moonshotai` provider: `kimi-k3` with
+  its 1,048,576-token context, 131,072-token output limit, default `max`
+  reasoning effort, and explicit `low`, `high`, and `max` variants.
+
+Provider keys never belong in Compose environment values or the image config.
+Use `opencode auth login` to update the mounted OpenCode auth store, including
+the canonical Moonshot credential under provider ID `moonshotai`. Direct
+OpenCode invocation is limited to auth, `opencode models <provider>` discovery,
+and bounded smoke checks. Threadwire remains the worker execution and streaming
+boundary for development tasks.
+
+## Startup
+
+Run the profile-free initializer before Docker creates the app container:
+
+```sh
+docker compose -f compose.dev.yaml up --build home-init
+docker compose -f compose.dev.yaml --profile app up --detach
+```
+
+`home-init` runs as `1000:1000`, mounts only `DEV_HOME_PATH`, and precreates
+every nested directory and file mount target. It receives no auth or context
+mounts.
+
+Run project commands in the persistent app service:
+
+```sh
+docker compose -f compose.dev.yaml exec app npm ci
+docker compose -f compose.dev.yaml exec app node --test test/container-dev.test.js
+docker compose -f compose.dev.yaml exec app npm run lint
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "threadwire",
-  "version": "0.1.13",
+  "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

@@ -24,9 +24,11 @@ const EXPECTED_FILES = [
   "bin/isolated-runtime.js",
   "bin/kimi-model-broker.js",
   "bin/model-broker.js",
+  "docs/capacity-admission.md",
   "docs/card-10520-plan.md",
   "docs/container-runtime.md",
   "docs/delegated-result-protocol.md",
+  "docs/development-container.md",
   "docs/evidence-artifacts.md",
   "docs/isolated-provider-runtime.md",
   "package.json",
@@ -40,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",
@@ -50,6 +53,7 @@ const EXPECTED_FILES = [
   "src/isolated-runtime.js",
   "src/isolated-state.js",
   "src/isolated-worker.js",
+  "src/jsonl-record-spool.js",
   "src/kimi-model-broker-policy.js",
   "src/kimi-model-broker.js",
   "src/kimi-oauth-store.js",
@@ -66,6 +70,9 @@ const EXPECTED_FILES = [
   "src/providers/index.js",
   "src/providers/kimi.js",
   "src/providers/opencode.js",
+  "src/provider-capacity-codex.js",
+  "src/provider-capacity-kimi.js",
+  "src/provider-capacity.js",
   "src/relay.js",
   "src/relay-write.js",
   "src/run-worker.js",
@@ -123,6 +130,7 @@ async function main() {
       "--help"
     ], {env: npmEnvironment, maxBuffer: 10 * 1024 * 1024})
     assert.match(helpOutput, /^Usage: threadwire run /u)
+    assert.match(helpOutput, /threadwire capacity /u)
 
     await assert.rejects(
       execFileAsync("npm", [

package/src/absolute-deadline.js

@@ -2,7 +2,11 @@
 /* eslint-disable jsdoc/require-jsdoc */
 
 export class AbsoluteDeadline {
-  constructor(expiresAt, {signal, request, response, now = Date.now, timeoutMessage = "Operation timeout", disconnectMessage = "Caller disconnected"} = {}) {
+  /**
+   * @param {number | undefined} expiresAt
+   * @param {{signal?: AbortSignal, request?: import("node:http").IncomingMessage, response?: import("node:http").ServerResponse, now?: () => number, timeoutMessage?: string, disconnectMessage?: string, destroyRequestOnAbort?: boolean}} [options]
+   */
+  constructor(expiresAt, {signal, request, response, now = Date.now, timeoutMessage = "Operation timeout", disconnectMessage = "Caller disconnected", destroyRequestOnAbort = true} = {}) {
     if (expiresAt !== undefined && (!Number.isSafeInteger(expiresAt) || expiresAt <= now())) throw new Error(timeoutMessage)
     this.expiresAt = expiresAt
     this.now = now
@@ -27,13 +31,12 @@ export class AbsoluteDeadline {
     response?.once?.("close", this.abortResponse)
     this.socket?.once?.("close", this.abortSocket)
     this.timer = expiresAt === undefined ? undefined : setTimeout(() => this.controller.abort(new Error(timeoutMessage)), Math.max(1, expiresAt - now()))
-    this.signal.addEventListener("abort", () => request?.destroy?.(this.signal.reason), {once: true})
+    if (destroyRequestOnAbort) this.signal.addEventListener("abort", () => request?.destroy?.(this.signal.reason), {once: true})
     if (request?.aborted || (response?.destroyed && !response.writableEnded)) this.abortRequest()
   }
   remaining() {
     this.throwIfAborted()
     if (this.expiresAt === undefined) return undefined
-    if (this.expiresAt === undefined) return undefined
     const remaining = this.expiresAt - this.now()
     if (remaining <= 0) {
       this.controller.abort(new Error(this.timeoutMessage))