fix(iii-init): re-run worker install after an early boot crash

[guibeira]

Problem

A worker can get permanently stuck in function_not_found. Hit while following the quickstart:

$ iii trigger math::add_two_numbers a=10 b=20
Error: { "code": "function_not_found", "message": "Function math::add_two_numbers not found" }

caller-worker (TS, owns math::add_two_numbers) was crashing on boot:

Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@iii-dev/observability' imported from /workspace/src/worker.ts

The VM's node_modules had iii-sdk but not @iii-dev/observability — a declared, published dependency. The first npm install exited 0 but left an incomplete tree (transient partial install). The worker crashed before registering its functions, so the trigger never resolved.

Why it persists (the real bug)

build_libkrun_local_script runs setup/install once, gated by /var/.iii-prepared, and the dep dirs live in /var/iii/deps bind-mounted across restarts. The marker records only that install exited 0, not that the dep tree is complete. So a partial-but-exit-0 install gets frozen: every later boot reuses the broken deps and crashes on the same missing import. iii worker restart can't recover — only clearing the worker's artifacts does.

The transient install drop itself isn't reliably reproducible (a clean re-prep installs the package fine), so the durable fix targets the persistence, not the trigger.

Fix

PID-1 (iii-init) deletes /var/.iii-prepared when the worker child exits non-zero within 30s of its initial spawn, forcing the next boot to re-run install and self-heal. Guards:

• Process exits only, not signals — kill_for_shutdown uses SIGTERM; an intentional shutdown must not look like a crash.
• Timed from the initial spawn — a crash after a source-edit restart is a runtime bug, not bad deps, so it shouldn't trigger a reinstall.

Applies to both legacy and supervised modes.

Tradeoff

A worker with a genuine early-startup bug will re-run install on each boot. npm install/pip install are cheap and idempotent when deps are already complete, and the worker is crash-looping regardless — so this only adds self-heal attempts, never breaks a healthy worker.

Tests

• is_boot_failure_classifies_exits — exit vs signal, zero vs non-zero, inside vs outside the window.
• invalidate_prepared_marker_removes_and_tolerates_missing — removes an existing marker; a missing marker is a no-op.

cargo test -p iii-init green; cargo fmt/clippy clean.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
iii-website	Ready	Preview, Comment	Jun 18, 2026 1:18pm

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: ead99a06-399c-4555-a9ff-7b8364ce21ae

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/reprep-on-early-worker-crash

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}