threadwire 0.1.17 → 0.1.19

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+- Resolve native Kimi through the normal `PATH` (`kimi`) instead of requiring
+  `/usr/local/bin/kimi`; `THREADWIRE_KIMI_BIN` remains the explicit override.
+- Resolve native Codex through `THREADWIRE_CODEX_BIN` or normal `PATH` lookup,
+  falling back to `codex` rather than a Threadwire-specific structural adapter.
+
+- Add an optional trusted-controller Telegram relay handoff: the generated host launcher can securely read one bounded controller-only bot-token file after argument validation, export it only to Threadwire, and scrub its pointer before controller execution. Existing provider-boundary filtering keeps the token and pointer out of Docker provider argv/environment, task containers, source, prompts, and logs; omitting the option preserves the existing dotenv behavior.
+
+## 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.

package/README.md

@@ -30,21 +30,27 @@ 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 first executable `codex` found by left-to-right
+Unix lookup in the supplied `PATH`; if no safe candidate is found, it runs the
+normal `codex` command. 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. 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:
 
@@ -72,14 +78,36 @@ The target has the form `telegram:<chat-id>:<thread-id>` for topics, `telegram:<
 
 `--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>`.
 
-Provider tool-start and tool-finish events do not produce Telegram messages by default. Pass the boolean `--tool-messages` flag to opt in, as shown above. When enabled, each tool is one concise, silent status line rather than a pair of noisy start/finish notices: when a tool starts, Threadwire sends `🛠 [P42] Tool: <safe command or tool description>` (for example `🛠 [P42] Tool: command — git status --short`), and when that same tool finishes, it edits the original message in place so it begins `✅` instead — no second completion message is sent, and Telegram edits raise no notification. The command/description shows a safe CLI-style preview with credential-bearing values (tokens, passwords, keys, authorization/cookie forms, credentials in URLs) redacted and control characters stripped; only normalized Codex command-completion output may also be appended to that same edited status as a Telegram-native expandable HTML blockquote with the visible label `Output →`; it is credential-redacted, HTML-escaped, and Unicode-safe bounded. Stderr, reasoning, and every other raw provider result remain excluded. Use `--max-output-length <positive-integer>` to truncate only that preview Unicode-safely; omit the option for unlimited tool detail. A prompt may instead come from `--prompt-file` or piped stdin, and every source rejects blank/whitespace content. Arguments following `--` pass to the selected provider, except output-stream and session options owned by Threadwire. Native Kimi uses the caller's compatible configuration. Threadwire maps its public `--resume-session <exact-id>` option to Kimi's native `--session <exact-id>` option and owns `--prompt` plus `--output-format stream-json`. The caller environment or image must provide the Kimi executable at `/usr/local/bin/kimi` or set `THREADWIRE_KIMI_BIN`; a missing executable fails normally.
+Provider tool-start and tool-finish events do not produce Telegram messages by default. Pass the boolean `--tool-messages` flag to opt in, as shown above. When enabled, each tool is one concise, silent status line rather than a pair of noisy start/finish notices: when a tool starts, Threadwire sends `🛠 [P42] Tool: <safe command or tool description>` (for example `🛠 [P42] Tool: command — git status --short`), and when that same tool finishes, it edits the original message in place so it begins `✅` instead — no second completion message is sent, and Telegram edits raise no notification. The command/description shows a safe CLI-style preview with credential-bearing values (tokens, passwords, keys, authorization/cookie forms, credentials in URLs) redacted and control characters stripped; only normalized Codex command-completion output may also be appended to that same edited status as a Telegram-native expandable HTML blockquote with the visible label `Output →`; it is credential-redacted, HTML-escaped, and Unicode-safe bounded. Stderr, reasoning, and every other raw provider result remain excluded. Use `--max-output-length <positive-integer>` to truncate only that preview Unicode-safely; omit the option for unlimited tool detail. A prompt may instead come from `--prompt-file` or piped stdin, and every source rejects blank/whitespace content. Arguments following `--` pass to the selected provider, except output-stream and session options owned by Threadwire. Native Kimi uses the caller's compatible configuration. Threadwire maps its public `--resume-session <exact-id>` option to Kimi's native `--session <exact-id>` option and owns `--prompt` plus `--output-format stream-json`. The caller environment or image must provide `kimi` on `PATH` or set `THREADWIRE_KIMI_BIN`; a missing executable fails normally.
 
-Threadwire directly spawns the structurally separate terminal adapters `/opt/data/libexec/threadwire/codex`, `/opt/data/libexec/threadwire/claude`, `/usr/local/bin/kimi`, or `/opt/data/libexec/threadwire/opencode-local-fleet` with an argv array and `shell: false`. These libexec adapters hold the real provider-CLI logic and are never on a worker's `PATH`, so relaying can never recurse back into the front-door shims. Each spawn also sets `THREADWIRE_ACTIVE=1` in the provider child environment. The executable can be overridden per provider with `THREADWIRE_CODEX_BIN`, `THREADWIRE_CLAUDE_BIN`, `THREADWIRE_KIMI_BIN`, or `THREADWIRE_OPENCODE_BIN` for staged cutover and rollback. It does not impose a worker timeout. `SIGINT` and `SIGTERM` are forwarded to the worker as explicit cancellation. 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.
+Threadwire directly spawns the structurally separate terminal adapters `/opt/data/libexec/threadwire/codex`, `/opt/data/libexec/threadwire/claude`, `kimi` resolved from `PATH`, 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.
 
+A trusted host controller can generate its launcher with an absolute,
+controller-only Telegram bot-token file:
+
+```sh
+node scripts/install-local-launcher.js /opt/data/bin/threadwire \
+  --telegram-bot-token-file /run/secrets/threadwire_telegram_bot_token
+```
+
+After token-free argument validation, the launcher reads at most 8 KiB from a
+regular, non-symlink file that is not group/other-writable, exports
+`THREADWIRE_TELEGRAM_BOT_TOKEN` only to the Threadwire controller, and clears
+the file pointer. Threadwire's existing provider boundary removes the token and
+pointer before spawning any provider. The token file and value are never passed
+through Docker argv/environment, mounted or copied into the task container or
+source, added to prompts, or written to logs. Omitting the option preserves the
+existing `TELEGRAM_BOT_TOKEN` dotenv lookup.
+
 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, Kimi, or OpenCode session. Threadwire preserves the provider's native resume ordering and streaming options and never uses implicit latest-session behavior.

package/docs/capacity-admission.md

@@ -51,10 +51,15 @@ 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`, then the first executable `codex` found by
+  left-to-right Unix lookup in the supplied `PATH`; if no safe candidate is
+  found, it runs the normal `codex` command. 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. 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/container-runtime.md

@@ -101,6 +101,17 @@ Codex state persists at `/home/threadwire/.codex`. The Codex adapter reads only
 `exec`, removes its pointer, and removes every ingress value and pointer from
 the provider environment. Threadwire repeats ingress filtering before spawn.
 
+For a trusted host controller, `scripts/install-local-launcher.js` accepts
+`--telegram-bot-token-file <absolute-file>`. The generated launcher validates
+Threadwire arguments before credential access, then reads at most 8 KiB from a
+regular, non-symlink, non-group/other-writable file. It exports the resulting
+`THREADWIRE_TELEGRAM_BOT_TOKEN` only to the controller and clears the file
+pointer before execution. Threadwire and the libexec adapters scrub Telegram
+credentials and pointers before provider spawn, so neither the value nor file
+pointer enters Docker provider argv/environment, a task container, source,
+prompts, or logs. Without this installer option, the launcher retains its
+existing `TELEGRAM_BOT_TOKEN` dotenv behavior.
+
 Docker secrets are ordinary files in the same container mount namespace. A
 provider running as the same UID can open another mounted secret file and can
 inspect same-UID process state permitted by the kernel, even though ingress
@@ -188,7 +199,7 @@ Kimi source is not a host worktree. The task controller creates one labelled sou
 
 The checked-in standard `runtime` image installs Codex only: it does not install
 Kimi or provide Kimi credentials. Native Kimi therefore requires a caller image
-or environment that provides `/usr/local/bin/kimi` (or sets
+or environment that provides `kimi` on `PATH` (or sets
 `THREADWIRE_KIMI_BIN`); a missing executable fails normally. Never mount
 `threadwire-kimi-oauth`, its access/refresh tokens, or the auth home into the
 Threadwire runtime, supervisor, worker, workspace, or session-state volume.

package/docs/isolated-provider-runtime.md

@@ -157,8 +157,8 @@ logs; worker self-report is not the sole assertion.
 
 ## Optional isolated Kimi Code subscription boundary
 
-Normal `threadwire run --provider kimi` is native execution: it directly runs
-the caller-provided Kimi executable at `/usr/local/bin/kimi`, or the path in
+Normal `threadwire run --provider kimi` is native execution: it resolves the
+caller-provided `kimi` executable from `PATH`, or uses the path in
 `THREADWIRE_KIMI_BIN`. It does not select this isolated supervisor, broker, or
 model allowlist. The checked-in standard `runtime` image installs Codex only,
 so native Kimi needs a caller-supplied executable and fails normally when it is

package/package.json

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

package/scripts/install-local-launcher.js

@@ -7,13 +7,13 @@ import {discardStagedFiles, replaceFile, stageFile, syncDirectory} from "./atomi
 
 const repositoryRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..")
 
-/** @param {string} targetPath @param {Parameters<typeof stageFile>[2]} [operations] */
-export async function installLocalLauncher(targetPath, operations = {}) {
+/** @param {string} targetPath @param {Parameters<typeof stageFile>[2]} [operations] @param {{telegramBotTokenFile?: string | undefined}} [launcherOptions] */
+export async function installLocalLauncher(targetPath, operations = {}, launcherOptions = {}) {
   const entrypointPath = resolve(repositoryRoot, "bin/threadwire.js")
   await mkdir(dirname(targetPath), {recursive: true})
   const stagedFiles = []
   try {
-    const stagedFile = await stageFile(targetPath, launcherScript(entrypointPath), operations)
+    const stagedFile = await stageFile(targetPath, launcherScript(entrypointPath, undefined, launcherOptions), operations)
     stagedFiles.push(stagedFile)
     await replaceFile(stagedFile)
     await syncDirectory(dirname(targetPath))
@@ -23,11 +23,27 @@ export async function installLocalLauncher(targetPath, operations = {}) {
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  await installLocalLauncher(process.argv[2] ?? "/opt/data/bin/threadwire")
+  const arguments_ = process.argv.slice(2)
+  const firstArgument = arguments_[0]
+  let targetPath = "/opt/data/bin/threadwire"
+  if (firstArgument !== undefined && !firstArgument.startsWith("--")) {
+    targetPath = firstArgument
+    arguments_.shift()
+  }
+  let telegramBotTokenFile
+  while (arguments_.length > 0) {
+    const option = arguments_.shift()
+    if (option !== "--telegram-bot-token-file" || arguments_.length === 0) throw new Error(`Unknown or incomplete option: ${option}`)
+    telegramBotTokenFile = arguments_.shift()
+  }
+  if (telegramBotTokenFile !== undefined && !telegramBotTokenFile.startsWith("/")) throw new Error("Telegram bot-token file must be an absolute path")
+  await installLocalLauncher(targetPath, {}, {telegramBotTokenFile})
 }
 
-/** @param {string} entrypoint @param {string} [dotenvPath] */
-export function launcherScript(entrypoint, dotenvPath = "/opt/data/.env") {
+/** @param {string} entrypoint @param {string} [dotenvPath] @param {{telegramBotTokenFile?: string | undefined}} [launcherOptions] */
+export function launcherScript(entrypoint, dotenvPath = "/opt/data/.env", launcherOptions = {}) {
+  const telegramBotTokenFile = launcherOptions.telegramBotTokenFile
+  if (telegramBotTokenFile !== undefined && !telegramBotTokenFile.startsWith("/")) throw new Error("Telegram bot-token file must be an absolute path")
   return `#!/usr/bin/env bash
 # Generated by Threadwire's install:local-launcher script. Do not source the
 # shared dotenv: it contains unrelated credentials.
@@ -35,8 +51,9 @@ set -euo pipefail
 
 readonly THREADWIRE_ENTRYPOINT=${shellLiteral(entrypoint)}
 readonly THREADWIRE_DOTENV_PATH=${shellLiteral(dotenvPath)}
+threadwire_telegram_bot_token_file=${shellLiteral(telegramBotTokenFile ?? "")}
 
-unset TELEGRAM_BOT_TOKEN THREADWIRE_TELEGRAM_BOT_TOKEN
+unset TELEGRAM_BOT_TOKEN THREADWIRE_TELEGRAM_BOT_TOKEN THREADWIRE_TELEGRAM_BOT_TOKEN_FILE
 
 # Scope validation-only strictly to this launcher's own preflight below: clear any
 # inherited value so it can never leak into the real invocation and let it exit
@@ -71,27 +88,58 @@ while [[ "$#" -gt 0 ]]; do
 done
 
 if [[ "$threadwire_target" == file:* ]]; then
+  unset threadwire_telegram_bot_token_file
   exec node "$THREADWIRE_ENTRYPOINT" "\${threadwire_arguments[@]}"
 fi
 
-if [[ ! -r "$THREADWIRE_DOTENV_PATH" ]]; then
+telegram_bot_token=""
+if [[ -n "$threadwire_telegram_bot_token_file" ]]; then
+  threadwire_token_read_status=0
+  telegram_bot_token=$(node - "$threadwire_telegram_bot_token_file" <<'NODE'
+const fs = require("node:fs")
+const maximumBytes = 8192
+let descriptor
+try {
+  descriptor = fs.openSync(process.argv[2], fs.constants.O_RDONLY | fs.constants.O_NONBLOCK | fs.constants.O_NOFOLLOW)
+  const metadata = fs.fstatSync(descriptor)
+  if (!metadata.isFile() || metadata.size === 0 || metadata.size > maximumBytes || (metadata.mode & 0o077) !== 0) throw new Error("invalid")
+  const buffer = Buffer.alloc(maximumBytes + 1)
+  const bytesRead = fs.readSync(descriptor, buffer, 0, buffer.length, 0)
+  if (bytesRead > maximumBytes) throw new Error("invalid")
+  const value = buffer.subarray(0, bytesRead).toString("utf8").replace(/[\\r\\n]+$/, "")
+  if (value.length === 0 || /[\\r\\n\\0]/u.test(value)) throw new Error("invalid")
+  process.stdout.write(value)
+} catch {
+  process.stderr.write("threadwire: Telegram bot-token file is invalid.\\n")
+  process.exitCode = 2
+} finally {
+  if (descriptor !== undefined) fs.closeSync(descriptor)
+}
+NODE
+  ) || threadwire_token_read_status=$?
+  unset threadwire_telegram_bot_token_file THREADWIRE_TELEGRAM_BOT_TOKEN_FILE
+  if [[ "$threadwire_token_read_status" -ne 0 ]]; then
+    exit "$threadwire_token_read_status"
+  fi
+elif [[ ! -r "$THREADWIRE_DOTENV_PATH" ]]; then
+  unset threadwire_telegram_bot_token_file
   printf 'threadwire: required dotenv is not readable: %s\\n' "$THREADWIRE_DOTENV_PATH" >&2
   exit 2
-fi
-
-telegram_bot_token=""
-while IFS= read -r line || [[ -n "$line" ]]; do
-  case "$line" in
-    TELEGRAM_BOT_TOKEN=*) telegram_bot_token="\${line#TELEGRAM_BOT_TOKEN=}" ;;
-    "export TELEGRAM_BOT_TOKEN="*) telegram_bot_token="\${line#export TELEGRAM_BOT_TOKEN=}" ;;
+else
+  unset threadwire_telegram_bot_token_file
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    case "$line" in
+      TELEGRAM_BOT_TOKEN=*) telegram_bot_token="\${line#TELEGRAM_BOT_TOKEN=}" ;;
+      "export TELEGRAM_BOT_TOKEN="*) telegram_bot_token="\${line#export TELEGRAM_BOT_TOKEN=}" ;;
+    esac
+  done < "$THREADWIRE_DOTENV_PATH"
+
+  telegram_bot_token="\${telegram_bot_token%$'\\r'}"
+  case "$telegram_bot_token" in
+    \\"*\\") telegram_bot_token="\${telegram_bot_token:1:\${#telegram_bot_token}-2}" ;;
+    \\'*\\') telegram_bot_token="\${telegram_bot_token:1:\${#telegram_bot_token}-2}" ;;
   esac
-done < "$THREADWIRE_DOTENV_PATH"
-
-telegram_bot_token="\${telegram_bot_token%$'\\r'}"
-case "$telegram_bot_token" in
-  \\"*\\") telegram_bot_token="\${telegram_bot_token:1:\${#telegram_bot_token}-2}" ;;
-  \\'*\\') telegram_bot_token="\${telegram_bot_token:1:\${#telegram_bot_token}-2}" ;;
-esac
+fi
 
 if [[ -z "$telegram_bot_token" ]]; then
   printf 'threadwire: TELEGRAM_BOT_TOKEN is required in %s\\n' "$THREADWIRE_DOTENV_PATH" >&2

package/src/cli.js

@@ -415,7 +415,8 @@ export async function main(arguments_, dependencies = {}) {
         parsed.providerArguments,
         prompt,
         parsed.resumeSession,
-        providerEnvironment
+        providerEnvironment,
+        {cwd: parsed.cwd}
       )
       if (parsed.resumeSession !== undefined) admission.setContinuationHandle(parsed.resumeSession)
       if (destination.type === "telegram") {

package/src/provider-capacity-codex.js

@@ -1,10 +1,9 @@
 // @ts-check
 
 import {spawn} from "node:child_process"
-import {providerExecutable} from "./providers/executable.js"
+import {codexExecutable} from "./providers/executable.js"
 import {CapacityProbeError, DEFAULT_CAPACITY_TIMEOUT_MS, normalizeCodexRateLimits} from "./provider-capacity.js"
 
-const DEFAULT_EXECUTABLE = "/opt/data/libexec/threadwire/codex"
 const MAX_LINE_BYTES = 65_536
 const MAX_LINES = 1_024
 
@@ -17,6 +16,7 @@ const MAX_LINES = 1_024
  * @param {{
  *   env?: NodeJS.ProcessEnv,
  *   executable?: string | undefined,
+ *   executableResolution?: Parameters<typeof codexExecutable>[1],
  *   spawnImplementation?: typeof spawn | undefined,
  *   timeoutMs?: number
  * }} options
@@ -26,7 +26,7 @@ export async function probeCodexCapacity(options) {
   const environment = options.env ?? process.env
   const spawnImplementation = options.spawnImplementation ?? spawn
   const timeoutMs = options.timeoutMs ?? DEFAULT_CAPACITY_TIMEOUT_MS
-  const executable = options.executable ?? providerExecutable("THREADWIRE_CODEX_BIN", DEFAULT_EXECUTABLE, environment)
+  const executable = options.executable ?? codexExecutable(environment, options.executableResolution)
   const result = await appServerExchange(spawnImplementation, executable, environment, timeoutMs)
   return normalizeCodexRateLimits(result)
 }

package/src/providers/codex.js

@@ -1,16 +1,20 @@
 // @ts-check
 
-import {providerExecutable} from "./executable.js"
+import {codexExecutable} from "./executable.js"
 
-const DEFAULT_EXECUTABLE = "/opt/data/libexec/threadwire/codex"
-
-/** @param {string[]} providerArguments @param {string} prompt @param {string | undefined} [resumeSession] */
-export function buildCodexCommand(providerArguments, prompt, resumeSession, environment = process.env) {
+/**
+ * @param {string[]} providerArguments
+ * @param {string} prompt
+ * @param {string | undefined} [resumeSession]
+ * @param {NodeJS.ProcessEnv} [environment]
+ * @param {Parameters<typeof codexExecutable>[1]} [executableResolution]
+ */
+export function buildCodexCommand(providerArguments, prompt, resumeSession, environment = process.env, executableResolution = {}) {
   rejectOwnedArguments(providerArguments)
   const arguments_ = resumeSession === undefined
     ? ["exec", "--json", ...providerArguments, prompt]
     : ["exec", "resume", "--json", ...providerArguments, resumeSession, prompt]
-  return {executable: providerExecutable("THREADWIRE_CODEX_BIN", DEFAULT_EXECUTABLE, environment), arguments: arguments_}
+  return {executable: codexExecutable(environment, executableResolution), arguments: arguments_}
 }
 
 /** @param {string[]} arguments_ */

package/src/providers/executable.js

@@ -1,6 +1,12 @@
 // @ts-check
 
-import {accessSync, constants, statSync} from "node:fs"
+import {accessSync, constants, realpathSync, statSync} from "node:fs"
+import {resolve} from "node:path"
+
+const CODEX_FRONT_DOOR_EXECUTABLES = new Set(["/opt/data/bin/codex"])
+
+/** @typedef {(path: string) => boolean} ExecutableProbe */
+/** @typedef {{canonicalize?: ((path: string) => string) | undefined, cwd?: string | undefined, isExecutable?: ExecutableProbe | undefined, warn?: ((warning: string) => void) | undefined}} ExecutableResolutionOptions */
 
 /**
  * Resolve the terminal provider executable Threadwire spawns. The default is the
@@ -27,3 +33,70 @@ export function providerExecutable(overrideVariable, defaultPath, environment =
   }
   return defaultPath
 }
+
+/**
+ * Resolve Codex without consulting a bare command through spawn. A valid
+ * override wins, followed by executable PATH candidates in Unix lookup order.
+ * Known Threadwire front doors are skipped so a normal direct-CLI lookup cannot
+ * recurse into Threadwire.
+ * @param {NodeJS.ProcessEnv} [environment]
+ * @param {ExecutableResolutionOptions} [options]
+ * @returns {string}
+ */
+export function codexExecutable(environment = process.env, options = {}) {
+  const isExecutable = options.isExecutable ?? executableFile
+  const warning = options.warn ?? console.error
+  const canonicalize = options.canonicalize ?? realpathSync
+  const cwd = options.cwd ?? process.cwd()
+  const override = environment.THREADWIRE_CODEX_BIN
+  if (override !== undefined && override.length > 0 && isExecutable(override)) return override
+
+  const fallback = discoveredCodexExecutable(environment, cwd, isExecutable, canonicalize) ?? "codex"
+  if (override !== undefined && override.length > 0) {
+    warning(`threadwire: THREADWIRE_CODEX_BIN=${override} is not executable, falling back to ${fallback}`)
+  }
+  return fallback
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} environment
+ * @param {string} cwd
+ * @param {ExecutableProbe} isExecutable
+ * @param {(path: string) => string} canonicalize
+ * @returns {string | undefined}
+ */
+function discoveredCodexExecutable(environment, cwd, isExecutable, canonicalize) {
+  if (environment.PATH === undefined) return undefined
+  for (const directory of environment.PATH.split(":")) {
+    const candidate = resolve(cwd, directory, "codex")
+    if (CODEX_FRONT_DOOR_EXECUTABLES.has(candidate)) continue
+    const canonicalPath = canonicalExecutable(candidate, isExecutable, canonicalize)
+    if (canonicalPath !== undefined && !CODEX_FRONT_DOOR_EXECUTABLES.has(canonicalPath)) return candidate
+  }
+  return undefined
+}
+
+/**
+ * @param {string} path
+ * @param {ExecutableProbe} isExecutable
+ * @param {(path: string) => string} canonicalize
+ * @returns {string | undefined}
+ */
+function canonicalExecutable(path, isExecutable, canonicalize) {
+  if (!isExecutable(path)) return undefined
+  try {
+    return canonicalize(path)
+  } catch {
+    return undefined
+  }
+}
+
+/** @type {ExecutableProbe} */
+function executableFile(path) {
+  try {
+    accessSync(path, constants.X_OK)
+    return statSync(path).isFile()
+  } catch {
+    return false
+  }
+}

package/src/providers/index.js

@@ -13,10 +13,10 @@ import {buildOpenCodeCommand, createOpenCodeParser, createOpenCodeSessionId} fro
 /** @type {readonly ["codex", "claude", "kimi", "opencode"]} */
 export const PROVIDERS = ["codex", "claude", "kimi", "opencode"]
 
-/** @param {string} name @param {string[]} providerArguments @param {string} prompt @param {string | undefined} resumeSession @param {NodeJS.ProcessEnv} [environment] @returns {Provider} */
-export function createProvider(name, providerArguments, prompt, resumeSession, environment = process.env) {
+/** @param {string} name @param {string[]} providerArguments @param {string} prompt @param {string | undefined} resumeSession @param {NodeJS.ProcessEnv} [environment] @param {Parameters<typeof buildCodexCommand>[4]} [codexExecutableResolution] @returns {Provider} */
+export function createProvider(name, providerArguments, prompt, resumeSession, environment = process.env, codexExecutableResolution = {}) {
   if (name === "codex") {
-    const command = buildCodexCommand(providerArguments, prompt, resumeSession, environment)
+    const command = buildCodexCommand(providerArguments, prompt, resumeSession, environment, codexExecutableResolution)
     return {...command, name: "codex", parse: parseCodexEvent, sessionId: codexSessionId, health: extractProviderHealth}
   }
   if (name === "claude") {

package/src/providers/kimi.js

@@ -1,6 +1,6 @@
 // @ts-check
 
-const EXECUTABLE = "/usr/local/bin/kimi"
+const EXECUTABLE = "kimi"
 const ALIAS_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,63}$/u
 const SESSION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,511}$/u
 const TOOL_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/u

package/src/telegram-ingress/core.js

@@ -149,7 +149,7 @@ export async function dispatchWorker(job, config, dependencies = {}) {
   const deliveryIdentity = randomUUID()
   const admission = new DelegatedResultAdmission({output: {write: () => {}}})
   try {
-    provider = createProviderImpl(job.provider, [], job.prompt, undefined, providerEnvironment)
+    provider = createProviderImpl(job.provider, [], job.prompt, undefined, providerEnvironment, {cwd})
     const transport = createFetchTransportImpl(config.botToken, undefined, config.telegramRequestTimeoutMs)
     sender = createTelegramSenderImpl(job.target, transport)
     control = new WorkerControlImpl({