threadwire 0.1.5 → 0.1.8

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.8 - 2026-07-26
+
+- Add `threadwire run --transcript <path>` to durably capture the exact normalized
+  stdout JSONL protocol in a private, exclusive file while keeping activity logs
+  and scoped raw evidence artifacts separate.
+- Add an opt-in, fail-closed isolated Codex write runtime. A root-owned
+  supervisor launches one worktree-only worker per task while a separate narrow
+  model broker retains upstream credentials. Fresh/resume, secret rotation,
+  filesystem/network/socket escapes, configuration overrides and cleanup are
+  covered by adversarial Docker E2E.
+- Bind broker grants to dedicated trusted run-network listeners and an exact
+  allowlisted model/request schema; add stable worktree ancestry checks,
+  task-private persistent resume state, contained nested cwd and structured
+  Codex arguments. The Compose deployment is now an explicit opt-in override.
+- Allocate authenticated, uniquely labeled state per fresh Codex lineage;
+  reject volume adoption and nested worktree mounts; use Docker's structured
+  host-bind API; and require an explicit supervisor-side model allowlist.
+- Bound and eagerly expire preflight capabilities, serialize writable lineage
+  resumes, and automatically reconcile and garbage-collect authenticated state
+  volumes with restart-safe cleanup retry.
+- Bound active runs and Docker/broker operations through cleanup, reserve state
+  before awaited revalidation, autonomously close expired grant listeners, and
+  reconcile exactly owned workers and networks across every container state.
+- Abort accepted broker work and caller-disconnected runs at one absolute
+  deadline; make crash cleanup authority an fsync'd authenticated full run
+  identity rather than labels; and durably fsync registry rename evidence.
+- Carry one launch deadline from preflight through prompt/secret/evidence/
+  Telegram setup, worker execution and cleanup; make supervisor and broker
+  shutdown abort control uploads and active work; move Docker GC outside the
+  registry transaction; and stream-cap broker/runtime responses.
+- Gate worker start on one-shot activation of a verified pending broker grant
+  and address its listener by the inspected per-run IP, removing dynamic
+  network-alias readiness races.
+- Route relay-profile Telegram Codex jobs exclusively through the isolated
+  runtime, keep validate-only launches local, preserve bounded stdout/stderr
+  evidence channels, and protect live lineages from concurrent reconciliation.

package/README.md

@@ -7,6 +7,13 @@ non-root Codex provider, Docker secrets, loopback TLS proxy, verification, and
 rollback path, see [Container runtime](docs/container-runtime.md). The legacy
 host launcher below remains supported and is separate from that deployment.
 
+Relay-originated Codex writes are explicit and default off. `--relay-write`
+requires a reviewed `--workspace-profile` plus the root-owned isolated runtime
+and credential broker. The worker gets one writable task worktree, no upstream
+or Git credential, and no route except its run-scoped broker. Missing
+prerequisites fail before prompt or credential reads with no native fallback.
+See [Isolated provider runtime](docs/isolated-provider-runtime.md).
+
 ## Run with npx
 
 Threadwire requires Node.js 22 or newer. Run the published CLI without a global
@@ -67,19 +74,25 @@ Threadwire directly spawns the structurally separate terminal adapters `/opt/dat
 
 The relay contract: the caller supplies `THREADWIRE_TARGET` (`telegram:<chat-id>` or `telegram:<chat-id>:<thread-id>`) and, optionally, `THREADWIRE_PROCESS_NUMBER`. The prompt arrives on a piped stdin; all native provider flags pass through after `--`. A positional prompt is never parsed. A missing `THREADWIRE_TARGET` fails closed (exit code 2) and a malformed one is rejected by the launcher's token-free preflight — the shim never invents a default destination and never silently downgrades a requested relay to a direct run. A shim relays only for a worker mode (`codex exec …`, `opencode-local-fleet run …`, or any non-interactive `claude …`); it drops the worker subcommand before relaying and Threadwire re-adds it around the prompt. Version and help queries, non-worker subcommands, interactive TTY sessions, and any invocation already inside a relayed run (`THREADWIRE_ACTIVE=1`, so nested provider workers stay local/native) run the real CLI directly through the libexec adapter.
 
-Pass `--resume-session <exact-provider-session-id>` to continue a stored Codex, Claude, or OpenCode session. Threadwire preserves the provider's native resume ordering and streaming options and never uses implicit latest-session behavior. To request a local JSONL activity log, pass `--activity-log <path>`. It writes only safe local facts: the selected workspace profile plus immutable workspace provenance, provider-started facts (`provider`, child `pid`), and session-available facts (`provider`, native `sessionId`). Raw events, reasoning, tool data, stderr, credentials, prompts, and Telegram token data are excluded. This activity log is local-only and is never enqueued for Telegram delivery.
+Pass `--resume-session <exact-provider-session-id>` to continue a stored Codex, Claude, 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.
+
+`--activity-log <path>` is different: it retains its append contract and writes only minimal safe lifecycle facts—the selected workspace profile and immutable provenance, provider start (`provider`, child `pid`), and available native session ID. It is local-only and never enters Telegram or normalized stdout.
 
 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's own stdout is a separate caller-facing JSON Lines protocol intended for an outer Hermes launcher. Each line is one JSON object and has no `version` key. It includes normalized `worker_started`, `worker_completed`/`worker_failed`, `tool_started`, `tool_finished`, and suitable `diagnostic` records, followed by exactly one terminal `{"type":"completed","exitCode":0,"assistantText":"..."}` record. When `--workspace-profile` is used, Threadwire first emits one `{"type":"execution_environment",...}` record containing the resolved profile name, in-container repository path, exact Git revision, and immutable worktree identity. Setup, worker, and relay-close errors use terminal exit code 2 while retaining the stderr diagnostic. The terminal `assistantText` is optional and is assembled from parsed assistant text deltas; deltas themselves are never streamed to stdout. Assistant text is credential-redacted, control-normalized, and capped at 16,384 Unicode code points. Tool names, details, and outputs use the relay's credential redaction and control normalization and are capped at 128, 1,024, and 4,096 code points respectively. Duplicate lifecycle phases and tool transitions are suppressed, and at most 64 nonterminal records are emitted per run; the terminal record is always exempt from that limit.
+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.
 
-This Hermes stdout channel does not replace Telegram: the existing human-readable Telegram relay continues independently. Provider stdout remains private input to Threadwire's JSONL parser and is never copied to Threadwire stdout; raw provider records, raw stdout, stderr, reasoning, prompts, tool inputs, and secrets are excluded. Threadwire's own error diagnostics remain on stderr. Help output is the sole non-run, human-readable stdout mode.
+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.
 
 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. 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.
 
 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.
 

package/TELEGRAM-INGRESS.md

@@ -1,6 +1,9 @@
 # Telegram Ingress for Threadwire
 
-Standalone Threadwire webhook service that accepts Telegram Bot API updates and launches Threadwire's existing worker path (`createProvider` → Telegram transport/sender → `NoticeQueue` → `Relay` → `runWorker`). Hermes is not involved.
+Standalone Threadwire webhook service that accepts Telegram Bot API updates.
+Native providers use the existing worker path; when isolated-runtime authority
+is configured, Codex uses isolated preflight/run exclusively with no native
+fallback. Hermes is not involved.
 
 ## Important bot ownership
 
@@ -49,7 +52,10 @@ The process binds to **loopback (`127.0.0.1`) by default**. Expose it only throu
 - Provider child env strips Telegram tokens, webhook secret, allowlists, bind/port, concurrency, tool-message, and update-guard service config. `runWorker` also strips Telegram tokens.
 - No logging of headers, bodies, prompts, or secrets.
 - Webhook secret must be at least 32 characters after trim.
-- Accepted work returns `202` only after the worker child has actually spawned (`onSpawn`); process completion alone is never treated as dispatch success.
+- Native work returns `202` only after the worker child has actually spawned
+  (`onSpawn`). Isolated Codex work returns `202` only after the authenticated
+  isolated run completes successfully; preflight alone is never treated as
+  dispatch success.
 - Failure before spawn rejects the request with `500` and is reported once via the operational error reporter.
 - Failure after spawn is reported once via the worker-failure reporter (not double-reported through both channels in the real entrypoint wiring).
 - Authenticated irrelevant updates return `200`.

package/bin/isolated-runtime.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import {startIsolatedRuntime} from "../src/isolated-runtime.js"
+
+await startIsolatedRuntime()

package/bin/model-broker.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import {startModelBroker} from "../src/model-broker.js"
+
+await startModelBroker()

package/docs/card-10520-plan.md

@@ -0,0 +1,45 @@
+# Card 10520 scoped implementation plan
+
+## Existing information flow
+
+1. `src/cli.js` reads the prompt, resolves the provider command, and gives both to
+   `runWorker`.
+2. `src/run-worker.js` spawns the provider, incrementally frames stdout JSONL,
+   calls `onRecord` with each raw provider record, normalizes it through the
+   provider parser, and serially calls `onEvent`. Stderr is currently reduced to
+   one diagnostic; its bytes are discarded.
+3. `src/cli.js` sends normalized events to `WorkerControl`, which renders bounded
+   progress to the explicit Telegram target. `ActivityLog` separately records
+   only workspace provenance, PID, and resumable session identifiers.
+4. The same normalized stream reaches `DelegatedResultAdmission`, but only
+   assistant text is accumulated. On termination, admission writes exactly one
+   bounded `delegated_result` JSON object to stdout. That stdout object is the
+   parent-facing result; tool/provider records are not emitted there.
+
+The current boundary therefore avoids most raw-event admission, but detailed
+prompt/provider/tool/stderr evidence is discarded or reduced and cannot be
+retrieved through an opaque, scoped contract.
+
+## Ownership and implementation
+
+`EvidenceStore` is the sole persistence and retrieval owner. `runWorker`
+remains the streaming/process-lifecycle owner and exposes raw stdout and stderr
+chunks to one evidence sink with its existing serial backpressure. `cli.js` and
+authenticated Telegram `dispatchWorker()` each own one run-scoped artifact and
+finalize it with the worker lifecycle. CLI admission and the owning Telegram
+topic receive only the bearer handle. `ActivityLog` does not duplicate evidence.
+
+Work proceeds RED-GREEN-REFACTOR:
+
+1. Add failing store and real CLI-pipeline tests proving the current retrieval
+   gap and specifying opaque IDs, permissions, atomic lifecycle, quotas,
+   recovery, cleanup, scope isolation, bounded reads, UTF-8/binary behavior, and
+   streaming redaction.
+2. Implement the pinned file-backed store and authenticated CLI/Telegram bearer
+   retrieval boundaries, then connect both real provider/worker paths without
+   changing existing terminal/error semantics.
+3. Add deterministic concurrency, expiry, corruption, filesystem-attack, and
+   tool-heavy end-to-end coverage; document operation and run every repository
+   check before a full diff/security audit and commit.
+
+Card 10521 metrics and admission-policy expansion are explicitly out of scope.

package/docs/container-runtime.md

@@ -97,8 +97,9 @@ node bin/threadwire.js run \
   --prompt 'Inspect the container worktree.'
 ```
 
-Provider activity/state persists at `/var/lib/threadwire/activity` and
-`/home/threadwire/.codex`. The Codex adapter reads only
+Provider activity persists at `/var/lib/threadwire/activity`, detailed
+delegated evidence persists privately at `/var/lib/threadwire/evidence`, and
+Codex state persists at `/home/threadwire/.codex`. The Codex adapter reads only
 `OPENAI_API_KEY_FILE`, exports the provider credential immediately before
 `exec`, removes its pointer, and removes every ingress value and pointer from
 the provider environment. Threadwire repeats ingress filtering before spawn.

package/docs/delegated-result-protocol.md

@@ -0,0 +1,161 @@
+# Delegated-result admission protocol
+
+Threadwire has two deliberately separate output planes:
+
+- Telegram is the user-visible progress plane. It may receive assistant streaming,
+  lifecycle notices, diagnostics, and opt-in tool status.
+- Standard output for a normal `threadwire run` is the parent-model admission
+  plane. It contains exactly one newline-terminated terminal JSON envelope.
+
+Standard error remains a caller diagnostic channel and is never admission
+content. Provider stdout is private parser input.
+
+## Context-budget metrics
+
+Each delegated run emits one concise `threadwire-context-metrics` JSON record
+on standard error. It contains content-free integer counters only. Detailed
+fixed-class counters are appended to the run's existing file-backed evidence
+artifact when evidence is configured; they are never added to the admission
+envelope.
+
+Byte counters are UTF-8 byte counts. Event and handle counters are counts.
+`estimatedTokens` is `ceil(admittedBytes / 4)` and is explicitly an estimate,
+not provider tokenization. Every counter saturates at 2,147,483,647. Metric
+classes and envelope-field names are closed, fixed sets, so worker-controlled
+values cannot create labels or cardinality. Counters retain no child text,
+commands, arguments, output, secrets, handles, reference values, or other raw
+values.
+
+The raw-child counters separately measure provider stdout/stderr stream chunks
+and bytes at the child stream boundary, and successfully JSON-parsed provider
+records at the parser boundary. A parsed record is not an OS chunk: one chunk
+may contain multiple records and one record may span chunks. Rejected counters
+distinguish provider stream, stderr, and lifecycle, diagnostic, and tool
+progress excluded from admission.
+
+Progress has fixed `attempted`, `suppressed`, `coalesced`, and `delivered`
+classes. Attempted sizes are JSON-encoded normalized-event bytes. Suppressed
+counts progress disabled by policy, while coalesced counts rendered assistant
+notices merged under notifier saturation. Delivered alone means a rendered
+message or edit was successfully sent; its size is the exact UTF-8 size of the
+JSON-encoded transport value. Consequently batching, rendering, and escaping
+may make delivered sizes differ from attempted sizes.
+
+Artifact counters measure finalized logical payload bytes and admitted
+opaque-handle count. When detailed metrics are the last event in that same
+artifact, `artifacts.bytes` is a fixed-point projection that includes the
+newline-terminated metrics JSON itself. Finalization must equal the projection
+or the run fails closed. This avoids a second metrics artifact while giving the
+stored record exact self-inclusive semantics.
+
+`admitted.bytes` and `parentContextDeltaBytes` measure the exact UTF-8 bytes of
+the newline-terminated terminal envelope written to stdout. Admitted field
+sizes are the UTF-8 sizes of each field's JSON-encoded value, including string
+quotes, escapes, and multibyte encoding.
+
+The regression invariant is exact: given quiet and tool-heavy runs with the
+same terminal conclusion, validation, references, and artifact handles, every
+admitted semantic field is identical and:
+
+```text
+heavy.parentContextDeltaBytes
+  <= quiet.parentContextDeltaBytes + 256
+```
+
+The 256-byte allowance is fixed metadata headroom and is independent of raw
+event volume. The current version adds no per-run metric metadata to parent
+context, so equivalent envelopes normally have equal deltas. Tests deliberately
+inject a provider-transcript-shaped conclusion large enough to exceed the
+allowance; this makes accidental stream admission fail deterministically.
+
+## Version 1 envelope
+
+The closed envelope has these required fields:
+
+```json
+{
+  "version": 1,
+  "type": "delegated_result",
+  "state": "completed",
+  "exitCode": 0
+}
+```
+
+`state` is exactly one of `completed`, `failed`, `blocked`, or
+`needs_decision`. `exitCode` is a nonnegative safe integer. The CLI currently
+produces `completed` for exit code zero and `failed` otherwise.
+
+The only optional fields are:
+
+| Field | Shape | Limit |
+| --- | --- | --- |
+| `conclusion` | string | 16,384 Unicode code points |
+| `blocker` | string | 1,024 Unicode code points |
+| `decisionRequest` | string | 1,024 Unicode code points |
+| `continuationHandle` | opaque ASCII provider token | 512 characters |
+| `artifactHandles` | array of opaque ASCII IDs or safe POSIX-style paths | 16 entries; 512 characters each |
+| `references` | array of `{kind,value}` | 16 entries; 2,048 code points per value |
+| `validationSummary` | string | 2,048 Unicode code points |
+
+A reference `kind` is exactly `commit` or `url`. Commit values are 7–64
+hexadecimal characters. URL values are non-whitespace HTTP or HTTPS URLs
+without embedded credentials.
+Artifact handles are opaque identifiers only; artifact content is forbidden.
+The complete UTF-8 JSON envelope is limited to 98,304 bytes.
+
+Threadwire preserves accepted continuation handles, artifact handles, and
+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.
+
+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
+such as `ses_123`, and namespaced IDs such as `provider:session-123` without
+admitting prose. Empty segments and known URL/transport scheme prefixes are
+forbidden. An artifact handle uses a single segment's alphabet and may
+additionally use `/` separators with one optional leading `/`; empty, `.` and
+`..` path components are forbidden. Both handle types reject whitespace,
+backslashes, controls (including C0, C1, and ESC), URL forms, userinfo, query
+strings, and fragments.
+
+## Fail-closed rules
+
+Admission is an explicit allowlist, not a projection of arbitrary provider
+data. A candidate is rejected if it:
+
+- has an unknown field or terminal state;
+- uses a wrong or nested type, including an object mislabeled as an allowed
+  string or opaque handle;
+- adds fields inside a reference;
+- has an empty, oversized, or over-cardinality optional collection;
+- contains an invalid commit or URL reference; or
+- exceeds a per-field or aggregate limit.
+
+Unknown normalized worker event kinds fail the run. Known lifecycle,
+diagnostic, and tool events remain progress-only and cannot affect the
+envelope. Threadwire does not silently remove a forbidden field and admit the
+remainder.
+
+## Excluded material
+
+The admission envelope never contains execution-environment progress,
+lifecycle progress, diagnostics, provider records or streams, tool names,
+arguments, details, commands or raw output, stderr, prompts,
+narration/reasoning, full transcripts, or artifact content. Optional structured
+fields are populated only from explicit trusted facts; provider prose is not
+parsed to invent them.
+
+## Caller obligations and compatibility
+
+The caller must parse exactly one envelope, require `version: 1` and
+`type: "delegated_result"`, enforce this closed schema, and reject missing,
+duplicate, trailing, unknown-version, unknown-field, or oversized records
+before parent transcript or context persistence. Standard error and Telegram
+delivery must never be merged into parent context.
+
+This protocol is the default and is an intentional pre-1.0 breaking change.
+Callers of the former unversioned mixed progress stream must upgrade before
+using this release. Future file-backed evidence may use opaque
+`artifactHandles`; retrieval and artifact storage are outside version 1 and are
+not implied by a handle.

package/docs/evidence-artifacts.md

@@ -0,0 +1,106 @@
+# Delegated-worker evidence artifacts
+
+Threadwire retains detailed delegated-worker evidence without adding it to the
+parent admission stream. Telegram uses the dedicated
+`/var/lib/threadwire/evidence` volume. A standalone run enables the same store
+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.
+
+## Security and lifecycle
+
+The Linux-only store walks an absolute path from a pinned `/` descriptor,
+opening every existing component with `O_DIRECTORY|O_NOFOLLOW`. It accepts
+root-owned non-writable ancestors, root-owned sticky directories such as
+`/tmp`, and same-user directories that are not group/world-writable. Only a missing final component is
+created, relative to its pinned trusted parent, as an owned `0700` directory.
+The store then performs child operations through `/proc/self/fd`; destructive
+work rechecks device/inode. Payload and metadata
+files are `0600`, regular, single-link files. Reconciliation removes only
+recognized implementation-owned artifact and atomic-temporary names. Any
+unknown entry is preserved and makes store opening fail closed.
+
+Only one live deployment can open a shared-volume root. The parent opens the
+lock file through the pinned root descriptor and authenticates `/usr/bin/flock`
+through its own descriptor. A synchronous child executes that inherited
+executable descriptor and applies `flock -n` to an inherited duplicate of the
+lock-file open description. The child emits no output and exits; the parent
+retains the locked open description until close or process death.
+
+Each event has a bounded kind and length frame, preserving ordering, binary
+data, and split-record provenance without accumulating a transcript in memory.
+Pending evidence counts against quotas, is unreadable, and is not expiry-cleaned
+while active. Fsync and atomic rename publish payload before ready metadata.
+Startup removes partial/corrupt states and rehydrates only exact-schema,
+unexpired ready artifacts.
+
+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.
+Durable reservations include metadata publication overlap and directory-entry
+allowance, so zero-event artifacts consume capacity.
+
+## Authorization and retrieval
+
+The `evidence_…` handle is a 256-bit bearer capability returned only through the
+owning parent envelope or Telegram topic. Metadata stores its SHA-256 binding,
+not the capability. Artifact redaction policy is AES-GCM sealed under the
+capability with versioned AAD binding every immutable lifecycle/accounting
+field. Ready metadata also contains an HMAC-SHA-256 commitment over the complete
+ordered framed payload, keyed from the bearer without storing the key.
+Ephemeral in-process owner objects are tracked only by weak identity membership;
+completed webhook jobs do not accumulate in an enumerable authorization registry.
+
+Telegram retrieval also requires an authenticated webhook update whose
+allowlisted sender and server-derived chat/topic/sender identity match the
+artifact metadata and encrypted-policy AAD. A requester
+cannot submit destination, run, or agent identity. Wrong scope, bad capability,
+missing, corrupt, removed, and expired artifacts all report generic
+unavailability.
+
+Parent retrieval syntax:
+
+```console
+threadwire evidence read --handle evidence_<bearer> --bytes 2048:512
+threadwire evidence read --handle evidence_<bearer> --lines 40:5
+threadwire evidence read --handle evidence_<bearer> --query "exact command identity" --context-bytes 80
+```
+
+Authenticated Telegram syntax is
+`/evidence evidence_<bearer> bytes 2048:512` or a bounded `lines` selector in
+the owning chat/topic.
+
+Byte offsets are zero-based bytes in the redacted logical stream. Line starts
+are one-based and include terminating newlines. Text boundaries are valid UTF-8;
+binary output is base64. Queries are bounded UTF-8 literal searches—never
+regular expressions. One universal encoded output-byte maximum applies even to
+one huge line. Verification should request the smallest useful excerpt.
+
+Retrieval opens the payload once with `O_NOFOLLOW`, verifies the descriptor, and
+in one bounded-memory streaming pass authenticates the exact raw frames while
+parsing, redacting, and retaining only the bounded selection. It drains through
+EOF and releases that selection only after timing-safe commitment verification;
+there is no authenticated-then-reread interval. It does not read whole artifacts
+or build transcript-wide offset arrays. Known runtime secret values, securely read secret-file contents,
+and their pointer values become `[REDACTED]`; responses state whether they were
+redacted or truncated. This finite policy is defense in depth, not
+arbitrary-secret detection.
+
+## Operations
+
+Run `cleanup()` from maintenance and use scoped removal for revocation. Cleanup
+is idempotent, skips active descriptor-pinned readers, fsyncs the root after
+unlink, and releases capacity only after that transaction succeeds. Trusted
+structured references already approved through the admission boundary remain
+independent of artifact cleanup. No provider currently supplies authenticated
+structured commit or URL metadata, so production does not infer either from
+stdout or ambient repository state.
+
+Treat the volume as sensitive provider-transcript data. Exclude it from general
+logs and broad backups. Any required backup must be encrypted and preserve the
+same authorization and retention. Suppressed raw content is never logged.

package/docs/isolated-provider-runtime.md

@@ -0,0 +1,137 @@
+# Isolated provider runtime
+
+Relay-originated Codex writes are disabled unless the caller supplies both
+`--relay-write` and a reviewed `--workspace-profile`. The write path never
+falls back to the native provider launcher.
+When the Telegram service is configured with isolated-runtime authority, Codex
+webhook jobs use the same preflight/run boundary exclusively; an unavailable
+runtime fails the job rather than invoking the native runner. Raw provider
+stdout and stderr are returned as separately identified, bounded chunks for
+the existing evidence callbacks.
+
+## Security boundary
+
+Telegram ingress has neither provider secrets nor container-runtime authority.
+The root-owned isolated-runtime supervisor has Docker authority and a read-only
+view of allowlisted worktree roots, but no provider credential. The model
+broker alone mounts the upstream credential. Each grant creates a listener
+bound to the broker's trusted per-run network interface. That listener accepts
+one token, one run/network lineage, one allowlisted model, and a closed
+`/v1/responses` schema; it is not a generic HTTP proxy.
+The listener remains non-authorizing while the supervisor creates and verifies
+the worker. The supervisor then activates it exactly once immediately before
+worker start. Workers receive the inspected per-run broker IP directly, so
+launch does not depend on asynchronous container-DNS alias propagation.
+
+For each fresh or explicit-resume run the supervisor creates a unique Docker
+internal network, attaches the broker, and launches an immutable worker. The
+worker has a read-only root, all capabilities dropped, no-new-privileges,
+container-local tmp/run, resource limits, and exactly one writable
+worktree mount. It has no host home, common Git directory, sibling worktree,
+host temp, shared provider state, secret, Docker/SSH socket, or external route. Its
+short-lived broker grant is revoked during cleanup.
+The grant owns one absolute deadline and every accepted socket. Expiry,
+explicit revoke, credential reload, or broker shutdown aborts an incomplete
+upload or upstream request, destroys accepted sockets, and closes the listener;
+authorization is checked again after the bounded request body is acquired.
+
+Codex state lives in a unique, random, immutable-label Docker volume for each
+fresh lineage, never a host or common Codex home. An HMAC-authenticated,
+root-private supervisor registry maps returned session IDs to that exact
+volume. Resume revalidates the volume's owner, namespace, task, and lineage
+labels before every mount. A collision, unlabeled or differently labeled
+preexisting volume, sibling,
+missing, expired, or lost state fails before worker creation.
+Only one worker may mount a lineage at a time; the supervisor holds an atomic
+reservation from preflight consumption through worker cleanup. Expired aliases
+are removed by authenticated periodic GC. The registry retains lineage
+ownership until Docker confirms deletion, retries cleanup failures, and
+reconciles exactly labelled orphan volumes on startup while preserving volumes
+referenced by in-process runs. On restart, exactly owned created, running, or
+exited orphan workers and their networks are removed before volume GC retries.
+An fsync'd, HMAC-authenticated run record binds the generated names, pinned
+image digest, entrypoint policy, private network, state volume, and exact
+worktree mount source/options. Reconciliation inspects that full identity and
+network endpoint membership; forgeable labels or any mismatched name, image,
+mount, option, command, or endpoint are never deletion authority.
+
+Preflight verifies Docker, the immutable image, broker readiness, the
+allowlisted non-symlink worktree with no nested mounts, stable device/inode ancestry, and mount policy before prompt, Telegram
+token, dotenv, evidence, resume state, executable override, or provider
+credential reads. The ancestry is revalidated immediately before container
+creation and start, and the immutable entrypoint verifies the mounted worktree
+and reviewed nested cwd before Codex. Only `--model` and `--color` are accepted;
+they are transported as a JSON array and passed exactly once without shell
+splitting. All other provider arguments are rejected before launch.
+Authenticated preflight admission has strict endpoint/field size limits,
+global and per-task caps, and an eager timer sweep, so abandoned capabilities
+expire without requiring a matching `/run`.
+Consumed capabilities enter a separate global/per-task active-run admission
+before validation can yield. The lineage reservation is acquired synchronously
+at that boundary, preventing periodic GC from deleting resume state during
+revalidation. Docker and broker operations have bounded deadlines, and each
+worker has a bounded operator-configured lifetime; timeout cleanup revokes the
+grant and removes the exactly labelled worker and network before capacity is
+released.
+The relay creates one absolute launch deadline before preflight. The same
+deadline and cancellation signal span prompt/stdin and file-secret reads,
+evidence and Telegram setup, Docker setup, broker readiness, execution,
+response/log reads, upstream work and exact cleanup. A disconnected caller or
+supervisor shutdown aborts its run. Independent per-step timeouts cannot extend
+the overall budget, and response bodies are stream-limited to 2 MiB.
+
+Codex bypasses its nested sandbox only inside this mandatory outer container.
+Its task-private home contains only that lineage's session state; persisted
+config, rules, hooks, plugins, MCP files and instruction files are rejected
+before Codex starts. MCP is forced empty and project instruction loading is disabled.
+Failure to create the outer boundary is fatal.
+
+## Deployment and rotation
+
+The default `compose.yaml` contains no provider secret, broker, supervisor, or
+Docker socket. Enable writes only with both files and the explicit profile:
+
+```sh
+docker compose -f compose.yaml -f compose.relay-write.yaml --profile relay-write up
+```
+
+The override fails interpolation unless every required image, control token,
+worktree root, allowlist and credential-file setting is present. Set immutable supervisor, broker, and worker images; a host
+`THREADWIRE_WORKSPACE_ROOT`; JSON `THREADWIRE_ALLOWED_WORKTREE_ROOTS`; separate
+runtime and broker control tokens; `THREADWIRE_ALLOWED_CODEX_MODELS` as a JSON
+server-side model allowlist; a unique `THREADWIRE_STATE_NAMESPACE`; a random
+`THREADWIRE_STATE_AUTH_KEY` of at least 32 characters; and a deployment secret file for the Codex
+credential. The supervisor alone receives `/var/run/docker.sock`. Restrict
+broker egress at the host/firewall to provider endpoints.
+
+The supervisor defaults to 16 active runs globally, two per reviewed task, a
+30-second maximum preflight slice, and a one-hour end-to-end launch deadline. Operators may
+lower these finite limits with `THREADWIRE_PREFLIGHT_TIMEOUT_MS`,
+`THREADWIRE_ACTIVE_RUN_CAPACITY`, `THREADWIRE_ACTIVE_TASK_CAPACITY`, and
+`THREADWIRE_WORKER_TIMEOUT_MS`; invalid, zero, or excessive values fail startup.
+
+The authenticated registry persists through file fsync, atomic rename, and
+parent-directory fsync. Startup removes only strictly named abandoned temp
+files whose complete contents authenticate under the deployment key; malformed
+or foreign files are left untouched for operator inspection.
+
+`THREADWIRE_WORKTREE_VOLUME` is only for nested-Docker/test deployments. Docker
+volume `Subpath` still mounts only the selected task directory. Production uses
+the exact host bind through Docker's structured Mount API with private
+propagation. The supervisor verifies the resulting two-mount inventory before
+start, and the entrypoint independently rejects nested worktree mounts.
+
+Replace the broker secret atomically and restart it, or call authenticated
+`/admin/reload`. Reload increments the generation and revokes existing grants.
+Missing, writable, symlinked, empty, or oversized secret files keep it unready.
+
+If Docker, broker, pinned image, worktree, security option, or private network
+is unavailable, relay write fails closed. There is no native fallback.
+
+## Verification
+
+Run `npm run all-checks`, `npm run verify:package`, and
+`npm run test:isolated-runtime-e2e` with broker, runtime, hostile-probe,
+production relay-worker, and fake-upstream image variables documented
+by that script. E2E uses host-volume canaries and fake-upstream authorization
+logs; worker self-report is not the sole assertion.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "threadwire",
-  "version": "0.1.5",
+  "version": "0.1.8",
   "description": "Stream Codex, Claude, and OpenCode worker progress to an explicit Telegram destination",
   "keywords": [
     "ai-agent",
@@ -14,6 +14,7 @@
   "private": false,
   "type": "module",
   "files": [
+    "CHANGELOG.md",
     "bin/",
     "docs/",
     "scripts/",
@@ -22,6 +23,8 @@
     "threadwire.workspace-profiles.json"
   ],
   "bin": {
+    "threadwire-isolated-runtime": "bin/isolated-runtime.js",
+    "threadwire-model-broker": "bin/model-broker.js",
     "threadwire": "bin/threadwire.js",
     "threadwire-telegram-webhook": "bin/telegram-webhook.js"
   },
@@ -49,6 +52,7 @@
     "prepublishOnly": "npm run all-checks && npm run verify:package",
     "test": "node --test \"test/**/*.test.js\"",
     "test:container-e2e": "sh docker/test/production-e2e.sh",
+    "test:isolated-runtime-e2e": "sh docker/test/isolated-runtime-e2e.sh",
     "typecheck": "tsc --noEmit",
     "verify:package": "node scripts/verify-package.js"
   },