threadwire 0.1.15 → 0.1.18

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 0.1.18 - 2026-08-06
+
+- Autodiscover the direct Codex CLI for both worker runs and live capacity probes: after a valid `THREADWIRE_CODEX_BIN` and executable structural `/opt/data/libexec/threadwire/codex` adapter, resolve executable `codex` candidates in supplied `PATH` order while rejecting the `/opt/data/bin/codex` Threadwire front door and continuing lookup. Stale overrides name the selected fallback, and no safe candidate fails clearly without unchecked bare-command lookup.
+
+## 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.

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
@@ -30,21 +30,29 @@ installation:
 ```sh
 npx --yes threadwire@latest --help
 
-THREADWIRE_CODEX_BIN=/path/to/direct/codex \
-  npx --yes threadwire@latest run \
-    --provider codex \
-    --target telegram:-1001234567890:42 \
-    --cwd /path/to/repository \
-    --prompt 'Inspect the project.'
+npx --yes threadwire@latest run \
+  --provider codex \
+  --target telegram:-1001234567890:42 \
+  --cwd /path/to/repository \
+  --prompt 'Inspect the project.'
 ```
 
 Provide `THREADWIRE_TELEGRAM_BOT_TOKEN` through a trusted environment or secret
-manager; do not put the token in the command line. For Claude or OpenCode, use
-`THREADWIRE_CLAUDE_BIN` or `THREADWIRE_OPENCODE_BIN` respectively. The override
-must name the direct provider executable, never a Threadwire front-door shim,
-so the relay cannot recursively launch itself. Existing Threadwire hosts may
-omit the override when their reviewed `/opt/data/libexec/threadwire/*` adapters
-are installed.
+manager; do not put the token in the command line. Codex first uses a valid
+`THREADWIRE_CODEX_BIN`, then the executable structural adapter at
+`/opt/data/libexec/threadwire/codex`, then the first executable `codex` found by
+left-to-right Unix lookup in the supplied `PATH`. Relative and empty PATH
+entries resolve from the worker's `--cwd`. Candidates are canonically resolved
+and inspected before use; known Threadwire front doors such as
+`/opt/data/bin/codex`, including aliases to them, are rejected while lookup
+continues, preventing recursive relay. A stale override warns with the actual
+selected fallback, and no safe candidate retains the explicit structural path
+for the normal unavailable failure rather than spawning an unchecked bare
+command. Use
+`THREADWIRE_CODEX_BIN` only for an intentional custom/container adapter. For
+Claude or OpenCode, use `THREADWIRE_CLAUDE_BIN` or `THREADWIRE_OPENCODE_BIN`
+respectively; those overrides must name direct provider executables, never
+Threadwire front-door shims.
 
 To install the same commands globally instead:
 
@@ -68,7 +76,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>`.
 
@@ -76,6 +84,11 @@ Provider tool-start and tool-finish events do not produce Telegram messages by d
 
 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.
 
+For Codex in ordinary project images, the fixed structural path described above
+is only the preferred fallback after a valid override. When that adapter is not
+executable, Threadwire uses the first inspected safe `codex` candidate from
+`PATH` instead.
+
 ## Provider front-door shims
 
 `/opt/data/bin/codex`, `/opt/data/bin/claude`, and `/opt/data/bin/opencode-local-fleet` are Threadwire front-door relay shims. Install or refresh both them and their paired libexec adapters with `npm run install:provider-shims`; the installer generates all six scripts from the repo templates and never modifies runtime artifacts on its own. A worker invocation is routed through the `/opt/data/bin/threadwire` launcher so its activity streams to the caller's explicit Telegram destination; every non-worker mode runs the real provider CLI unchanged through the paired libexec adapter.
@@ -84,7 +97,7 @@ 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 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.
 
@@ -94,7 +107,7 @@ Provider stdout is decoded as JSONL with a finite 1 MiB UTF-8 byte limit for eac
 
 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.
 
@@ -104,9 +117,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/capacity-admission.md

@@ -51,10 +51,16 @@ pin before relying on it.
 
 - **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`).
+  executable resolves exactly like the Codex worker provider: a valid
+  `THREADWIRE_CODEX_BIN`, the executable structural
+  `/opt/data/libexec/threadwire/codex` adapter, then the first executable
+  `codex` found by left-to-right Unix lookup in the supplied `PATH`. Each PATH
+  candidate is canonically resolved and inspected before use; relative and
+  empty entries resolve from the probe's working directory. Known Threadwire
+  front doors, notably `/opt/data/bin/codex` and aliases to it, are skipped
+  while lookup continues; if no safe candidate exists, the probe reports
+  unavailable without spawning an unchecked bare command. A stale explicit
+  override warns with the selected fallback.
   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.

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.15",
+  "version": "0.1.18",
   "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/src/cli.js

@@ -1,8 +1,8 @@
 // @ts-check
 
-import {readFile} from "node:fs/promises"
+import {lstat, readFile, readlink, realpath} from "node:fs/promises"
 import {randomUUID} from "node:crypto"
-import {isAbsolute, normalize, resolve} from "node:path"
+import {basename, dirname, isAbsolute, join, normalize, resolve} from "node:path"
 import {stdin, stderr, stdout} from "node:process"
 import {createFetchTransport} from "./notifiers/fetch-transport.js"
 import {createTelegramSender, parseTelegramTarget} from "./notifiers/telegram.js"
@@ -30,7 +30,7 @@ import {
 import {probeCodexCapacity} from "./provider-capacity-codex.js"
 import {probeKimiCapacity} from "./provider-capacity-kimi.js"
 
-const HELP = `Usage: threadwire run --provider <codex|claude|kimi|opencode> --target telegram:<chat-id> | telegram:<chat-id>:<thread-id>
+const HELP = `Usage: threadwire run --provider <codex|claude|kimi|opencode> --target telegram:<chat-id> | telegram:<chat-id>:<thread-id> | file:<absolute-path>
   [--process-number <positive-integer>] [--cwd <directory>]
   [--relay-write]
   [--tool-messages] [--max-output-length <positive-integer>]
@@ -305,12 +305,20 @@ export async function main(arguments_, dependencies = {}) {
         await store.close()
       }
     }
-    if (!validateOnly) {
-      normalizedOutput = new NormalizedOutput(output, parsed.transcript)
+    const destination = parseDeliveryTarget(parsed.target)
+    if (destination.type === "file" && parsed.transcript !== undefined) {
+      throw new Error("--transcript cannot be combined with a file target")
     }
+    const transcriptPath = destination.type === "file" ? destination.path : parsed.transcript
+    if (
+      transcriptPath !== undefined && parsed.activityLog !== undefined
+      && await canonicalFilesystemPath(transcriptPath) === await canonicalFilesystemPath(parsed.activityLog)
+    ) {
+      throw new Error("Result and activity log paths must resolve to different filesystem paths")
+    }
+    if (!validateOnly) normalizedOutput = new NormalizedOutput(output, transcriptPath)
     const metrics = new ContextBudgetMetrics()
     runAdmission = normalizedOutput === undefined ? undefined : new DelegatedResultAdmission({output: normalizedOutput, metrics})
-    const target = parseTelegramTarget(parsed.target)
     if (parsed.relayWrite) validateRelayWriteProviderArguments(parsed.providerArguments)
     if (validateOnly) return 0
     const usesIsolatedRuntime = parsed.relayWrite
@@ -335,27 +343,63 @@ export async function main(arguments_, dependencies = {}) {
     let activity
     /** @type {Awaited<ReturnType<EvidenceStore["createArtifact"]>> | undefined} */
     let evidence
+    /** @type {Awaited<ReturnType<EvidenceStore["createArtifact"]>> | undefined} */
+    let resultEvidence
     /** @type {EvidenceStore | undefined} */
     let ownedEvidenceStore
+    /** @type {EvidenceStore | undefined} */
+    let evidenceStore
+    /** @type {{destinationId: string, runId: string} | undefined} */
+    let evidenceOwner
+    /** @type {WorkerControl | undefined} */
+    let control
+    /** @type {unknown} */
+    let deliveryError
+    let resultEvidenceFinalized = false
     let evidencePayloadBytes = 0
+    let resultEvidenceBytes = 0
+    const deliveryIdentity = randomUUID()
     const launchDeadline = isolatedPreflight?.deadline
     try {
-      environment = await boundedLaunch(resolveFileBackedSettings(sourceEnvironment, ["THREADWIRE_TELEGRAM_BOT_TOKEN"]), launchDeadline)
+      environment = await boundedLaunch(resolveFileBackedSettings(
+        sourceEnvironment,
+        destination.type === "telegram" ? ["THREADWIRE_TELEGRAM_BOT_TOKEN"] : []
+      ), launchDeadline)
+      if (destination.type === "telegram" && !environment.THREADWIRE_TELEGRAM_BOT_TOKEN) {
+        throw new Error("THREADWIRE_TELEGRAM_BOT_TOKEN is required")
+      }
       const prompt = await readPrompt(parsed, dependencies.input ?? stdin, launchDeadline?.signal)
       const configuredEvidenceRoot = evidenceRoot(sourceEnvironment.THREADWIRE_EVIDENCE_ROOT)
       if (dependencies.evidenceStore === undefined && configuredEvidenceRoot !== undefined) {
         ownedEvidenceStore = await boundedLaunch(EvidenceStore.open({root: configuredEvidenceRoot}), launchDeadline)
       }
-      const evidenceStore = dependencies.evidenceStore ?? ownedEvidenceStore
+      evidenceStore = dependencies.evidenceStore ?? ownedEvidenceStore
       if (evidenceStore !== undefined) {
-        const evidenceOwner = dependencies.evidenceOwnerScope ?? evidenceStore.createOwnerScope({
-          destinationId: `${target.chatId}:${target.threadId ?? "dm"}`,
-          runId: randomUUID()
+        evidenceOwner = dependencies.evidenceOwnerScope ?? evidenceStore.createOwnerScope({
+          destinationId: destination.type === "telegram"
+            ? `${destination.target.chatId}:${destination.target.threadId ?? "dm"}`
+            : "file",
+          runId: deliveryIdentity
         })
+        const redactions = await boundedLaunch(collectEvidenceRedactions(environment), launchDeadline)
         evidence = await evidenceStore.createArtifact(evidenceOwner, {
           contentType: "text/plain; charset=utf-8",
-          redactions: await boundedLaunch(collectEvidenceRedactions(environment), launchDeadline)
+          redactions
         })
+        try {
+          resultEvidence = await evidenceStore.createArtifact(evidenceOwner, {
+            contentType: "application/json",
+            redactions,
+            delivery: {
+              identity: deliveryIdentity,
+              state: destination.type === "telegram" ? "delivery_pending" : "delivery_not_requested"
+            }
+          })
+        } catch (error) {
+          await evidence.abort()
+          evidence = undefined
+          throw error
+        }
       }
       if (evidence !== undefined) {
         const promptEvidence = `prompt\n${prompt}\nprovider-stream\n`
@@ -371,20 +415,25 @@ export async function main(arguments_, dependencies = {}) {
         parsed.providerArguments,
         prompt,
         parsed.resumeSession,
-        providerEnvironment
+        providerEnvironment,
+        {cwd: parsed.cwd}
       )
       if (parsed.resumeSession !== undefined) admission.setContinuationHandle(parsed.resumeSession)
-      const token = environment.THREADWIRE_TELEGRAM_BOT_TOKEN
-      if (!token) throw new Error("THREADWIRE_TELEGRAM_BOT_TOKEN is required")
-      const transport = (dependencies.transportFactory ?? createFetchTransport)(token, undefined, parseTelegramRequestTimeoutMs(environment))
-      const control = new WorkerControl({
-        sender: createTelegramSender(target, transport),
-        processNumber: parsed.processNumber ?? process.pid,
-        toolMessages: parsed.toolMessages,
-        ...(dependencies.workerControlOptions ?? {}),
-        ...(parsed.maxOutputLength === undefined ? {} : {maxOutputLength: parsed.maxOutputLength}),
-        metrics
-      })
+      if (destination.type === "telegram") {
+        const transport = (dependencies.transportFactory ?? createFetchTransport)(
+          /** @type {string} */ (environment.THREADWIRE_TELEGRAM_BOT_TOKEN),
+          undefined,
+          parseTelegramRequestTimeoutMs(environment)
+        )
+        control = new WorkerControl({
+          sender: createTelegramSender(destination.target, transport),
+          processNumber: parsed.processNumber ?? process.pid,
+          toolMessages: parsed.toolMessages,
+          ...(dependencies.workerControlOptions ?? {}),
+          ...(parsed.maxOutputLength === undefined ? {} : {maxOutputLength: parsed.maxOutputLength}),
+          metrics
+        })
+      }
       activity = parsed.activityLog === undefined ? undefined : new ActivityLog(parsed.activityLog)
       activity?.recordController(process.pid)
       /** @type {import("./run-worker.js").RunWorkerOptions} */
@@ -397,7 +446,7 @@ export async function main(arguments_, dependencies = {}) {
         parse: provider.parse,
         ...(provider.completion === undefined ? {} : {completion: provider.completion}),
         ...(launchDeadline === undefined ? {} : {signal: launchDeadline.signal}),
-        onEvent: (event) => {
+        onEvent: async (event) => {
           validateNormalizedWorkerEvent(event)
           if (event.type !== "text-delta") {
             metrics.recordRejected(`${event.type}_progress`, Buffer.byteLength(JSON.stringify(event), "utf8"))
@@ -406,7 +455,13 @@ export async function main(arguments_, dependencies = {}) {
           else if (event.type === "tool") activity?.recordActivity(provider.name, "tool")
           else if (event.type === "lifecycle") activity?.recordActivity(provider.name, "lifecycle")
           acceptAdmissionEvent(admission, event)
-          return control.accept(event)
+          if (control !== undefined) {
+            try {
+              await control.accept(event)
+            } catch (error) {
+              deliveryError ??= error
+            }
+          }
         },
         onSpawn: (pid) => {
           if (activity && pid !== undefined) activity.recordStarted(provider.name, pid)
@@ -456,27 +511,73 @@ export async function main(arguments_, dependencies = {}) {
       } else {
         exitCode = await (dependencies.workerRunner ?? runWorker)(workerOptions)
       }
-      await boundedLaunch(control.close(), launchDeadline)
       terminalExitCode = exitCode
     } finally {
-      if (evidence !== undefined) {
+      const terminal = {state: /** @type {"completed" | "failed"} */ (terminalExitCode === 0 ? "completed" : "failed"), exitCode: terminalExitCode}
+      if (evidence !== undefined && resultEvidence !== undefined) {
+        try {
+          admission.addArtifactHandle(resultEvidence.handle)
+          const providerResult = admission.createProviderResult(terminal)
+          const serializedProviderResult = `${JSON.stringify(providerResult)}\n`
+          await resultEvidence.append("provider-result", serializedProviderResult)
+          const resultArtifact = await resultEvidence.finalize()
+          resultEvidenceBytes = resultArtifact.bytes
+          resultEvidenceFinalized = true
+        } catch (error) {
+          await evidence.abort()
+          await resultEvidence.abort()
+          admission.removeArtifactHandle(resultEvidence.handle)
+          metrics.clearArtifact()
+          terminalExitCode = 2
+          evidenceError = error
+        }
+      } else {
+        await evidence?.abort()
+        await resultEvidence?.abort()
+      }
+      if (control !== undefined) {
+        try {
+          await boundedLaunch(control.close(), launchDeadline)
+        } catch (error) {
+          deliveryError ??= error
+        }
+      }
+      if (evidence !== undefined && resultEvidenceFinalized) {
+        admission.addArtifactHandle(evidence.handle)
         try {
-          admission.addArtifactHandle(evidence.handle)
-          const terminal = {state: /** @type {"completed" | "failed"} */ (terminalExitCode === 0 ? "completed" : "failed"), exitCode: terminalExitCode}
           metrics.recordAdmission(admission.preview(terminal))
-          const projectedArtifactBytes = metrics.projectSelfInclusiveArtifact(evidencePayloadBytes, 1)
+          const projectedArtifactBytes = metrics.projectSelfInclusiveArtifact(
+            evidencePayloadBytes + resultEvidenceBytes,
+            2
+          )
           await evidence.append("context-metrics", `${JSON.stringify(metrics.snapshot())}\n`)
           const artifact = await evidence.finalize()
-          assertArtifactProjection(artifact.bytes, projectedArtifactBytes)
+          assertArtifactProjection(artifact.bytes + resultEvidenceBytes, projectedArtifactBytes)
         } catch (error) {
-          await evidence.abort()
           admission.removeArtifactHandle(evidence.handle)
+          await evidence.abort()
           metrics.clearArtifact()
-          terminalExitCode = 2
-          evidenceError = error
+          metrics.recordArtifact(resultEvidenceBytes, 1)
+          evidenceError ??= error
         }
+      } else if (resultEvidenceFinalized) {
+        metrics.recordArtifact(resultEvidenceBytes, 1)
       }
       admission.complete({state: terminalExitCode === 0 ? "completed" : "failed", exitCode: terminalExitCode})
+      if (
+        destination.type === "telegram" && resultEvidenceFinalized
+        && evidenceStore !== undefined && evidenceOwner !== undefined && resultEvidence !== undefined
+      ) {
+        try {
+          await evidenceStore.recordDelivery(
+            evidenceOwner,
+            resultEvidence.handle,
+            control !== undefined && deliveryError === undefined ? "delivery_succeeded" : "delivery_failed"
+          )
+        } catch (error) {
+          evidenceError ??= error
+        }
+      }
       errorOutput.write(`threadwire-context-metrics ${JSON.stringify(metrics.conciseDiagnostic())}\n`)
       if (activity !== undefined) {
         activity.recordTerminal(/** @type {"codex" | "claude" | "kimi" | "opencode"} */ (parsed.provider), terminalState(terminalExitCode), terminalExitCode)
@@ -486,6 +587,7 @@ export async function main(arguments_, dependencies = {}) {
       launchDeadline?.close()
     }
     if (evidenceError !== undefined) throw evidenceError
+    if (deliveryError !== undefined) throw deliveryError
     return terminalExitCode
   } catch (error) {
     let reportedError = error
@@ -507,6 +609,44 @@ export async function main(arguments_, dependencies = {}) {
   }
 }
 
+/** @param {string} value @returns {{type: "telegram", target: import("./types.js").TelegramTarget} | {type: "file", path: string}} */
+function parseDeliveryTarget(value) {
+  if (!value.startsWith("file:")) return {type: "telegram", target: parseTelegramTarget(value)}
+  const path = value.slice("file:".length)
+  if (!isAbsolute(path) || normalize(path) !== path || path.includes("\0") || path === "/") {
+    throw new Error("File target must contain a normalized absolute file path")
+  }
+  return {type: "file", path}
+}
+
+/** @param {string} path @param {Set<string>} [seen] @returns {Promise<string>} */
+async function canonicalFilesystemPath(path, seen = new Set()) {
+  if (seen.has(path)) throw new Error("Result or activity log path contains a filesystem alias cycle")
+  seen.add(path)
+  try {
+    return await realpath(path)
+  } catch (error) {
+    if (!missingPath(error)) throw error
+  }
+  try {
+    const metadata = await lstat(path)
+    if (metadata.isSymbolicLink()) {
+      return canonicalFilesystemPath(resolve(dirname(path), await readlink(path)), seen)
+    }
+  } catch (error) {
+    if (!missingPath(error)) throw error
+  }
+  const parent = dirname(path)
+  if (parent === path) return path
+  return join(await canonicalFilesystemPath(parent, seen), basename(path))
+}
+
+/** @param {unknown} error */
+function missingPath(error) {
+  return typeof error === "object" && error !== null
+    && /** @type {{code?: unknown}} */ (error).code === "ENOENT"
+}
+
 /** @param {string | undefined} value */
 function evidenceRoot(value) {
   if (value === undefined) return undefined