managed workers strand on non-default engine ports: spawn chain doesn't forward the manager port, and several worker builds ignore the injected engine URL

[paulefde]

Summary

Running the engine on a non-default iii-worker-manager port (anything
other than 49134) strands most managed registry workers in a
connect-retry loop against ws://127.0.0.1:49134. Three separate links in
the spawn chain contribute:

1. The engine spawns iii-worker worker-manager-daemon without passing
   --engine, so the daemon dials its default ws://127.0.0.1:49134
   even though env (III_URL, III_ENGINE_URL) points at the real port.
2. iii-worker start --port documents that "the engine passes its
   configured iii-worker-manager port when auto-spawning external workers so
   non-default manager ports don't silently break connectivity" — but on the
   daemon-mediated spawn path the port never reaches the worker process.
3. Several current worker builds ignore the engine URL the spawn chain
   injects and fall back to the compiled-in default. Observed on engine
   0.21.6 (macOS arm64): harness@1.3.3, session-manager@1.0.5,
   context-manager@1.0.4, iii-directory@1.0.3, web@1.2.2,
   queue@0.2.2 all retry 49134; llm-router@1.1.1,
   provider-anthropic@1.1.1, provider-openai@1.1.1 (rebuilt against the
   0.21.6 SDK on 2026-07-14) connect correctly. Manually launching
   ~/.iii/workers/harness with III_WS_URL=ws://127.0.0.1:<port> connects
   fine, so the binaries are port-capable — they just never receive the
   value they read.

Reproduction (engine 0.21.6, macOS arm64)

1. config.yaml with iii-worker-manager: { port: 3034 } (any non-default)
   plus registry workers including harness and session-manager.
2. Start the engine. llm-router and the providers register; harness,
   session-manager, web, queue, context-manager, iii-directory
   log iii_sdk::iii: failed to connect; retrying error=IO error: Connection refused until their startup deadline, then die (harness exits
   with configuration::get failed after 3 attempts).
3. ps shows the daemon as iii-worker worker-manager-daemon with no
   --engine argument, while its environment carries the correct
   III_URL/III_ENGINE_URL.

Expected

A non-default manager port should propagate through the entire spawn chain:
engine → daemon (--engine) → worker process (whatever env/flag the worker
build reads), with the worker builds honoring the injected URL rather than
the compiled default.

Why it matters

Multi-worktree / multi-engine dev setups remap ports per checkout by
design; today any such setup silently loses the whole managed-worker fleet
except the three newest builds. Our current workaround is a local TCP proxy
aliasing 49134 to the real engine port plus a wrapper script that appends
--engine to the daemon spawn — both of which we would love to delete.

[andersonleal]

All three links in the spawn chain are now fixed:

1. engine → worker-manager-daemon — MOT-3970 (fix(engine,iii-worker): pass engine's actual WS address to spawned builtin daemons (MOT-3970) iii#1974, in engine 0.21.8-next.2): the engine exports III_ENGINE_URL/III_URL to spawned builtin daemons, and the daemon's --engine falls back to that env.
2. port → worker process — fix(engine,iii-worker): propagate manager port to registry binary workers (MOT-4149) iii#2000 (merged, ships with the next 0.21.8 build): start_binary_worker now exports III_ENGINE_URL/III_URL derived from its --port; the registry auto-spawn exports the same pair for the whole detached tree (including source-watcher respawns); and daemon worker::start plus bare iii-worker start/restart resolve config.yaml's iii-worker-manager port instead of assuming 49134.
3. worker builds honoring the injected URL — (MOT-4149) fix: honor engine-injected III_URL in every worker URL arg #551, released today: every worker's URL arg now has a clap env = "III_URL" fallback. Rebuilt fleet includes harness 1.4.4, session-manager 1.0.9, context-manager 1.0.6, iii-directory 1.0.5, web 1.2.5, queue 0.21.1, llm-router 1.3.1, and all providers (anthropic 1.1.4, openai 1.1.6, xai 1.2.2, kimi 1.0.2, llamacpp 0.2.2, zai 0.4.2, openai-codex 0.3.2).

A note on III_WS_URL: no engine version has ever exported it — the workers that read it could never have received a URL that way. It has been dropped in favor of the documented contract (III_URL, with III_ENGINE_URL also exported) rather than adopted.

With an engine carrying iii-hq/iii#2000 and workers refreshed via iii worker update, the original repro (manager port 3034) boots the whole managed fleet — the TCP-proxy and daemon-wrapper workarounds can be deleted. Leaving this open pending confirmation on a real setup.