threadwire 0.1.17 → 0.1.18

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## 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.

package/README.md

@@ -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:
 
@@ -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.

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/package.json

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

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,13 @@
 // @ts-check
 
-import {accessSync, constants, statSync} from "node:fs"
+import {accessSync, constants, realpathSync, statSync} from "node:fs"
+import {resolve} from "node:path"
+
+const CODEX_STRUCTURAL_EXECUTABLE = "/opt/data/libexec/threadwire/codex"
+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 +34,71 @@ export function providerExecutable(overrideVariable, defaultPath, environment =
   }
   return defaultPath
 }
+
+/**
+ * Resolve Codex without consulting a bare command through spawn. A valid
+ * override wins, followed by the structural adapter and then 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_STRUCTURAL_EXECUTABLE
+  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 (isExecutable(CODEX_STRUCTURAL_EXECUTABLE)) return CODEX_STRUCTURAL_EXECUTABLE
+  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/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({