(MOT-4187) feat(iii-directory): version-aware skills reconcile

[rohitg00]

Problem

Skills for a namespace are downloaded once and then frozen. The boot reconcile skips any namespace with a .iii-skill-complete marker (reconcile_skips_existing_marker), so skills drift behind the worker they describe as iii worker update moves the installed version forward. On a live rig this left harness skills at 1.0.2 while harness 1.5.2 was running, with equivalent drift across ~18 namespaces.

Change

Two mechanisms close the gap, both keeping the existing overwrite semantics (file-by-file, hand-added sibling files survive):

• The worker trigger subscription now covers update as well as add. The download is pinned to the installed version: preferred from the version field on the event when present (the wire schema reserves it on terminal add/update stages), with a single worker::list lookup as fallback, then latest tag as before.
• The completion marker records the resolved semver when the download was pinned (version, additive optional field; legacy markers parse tolerantly as version-absent). With the new auto_refresh config field enabled, the boot reconcile compares the marker version against the installed worker version and re-downloads on mismatch. A marker without a recorded version converges to a versioned marker on its first refresh pass.

auto_refresh defaults to false: without it, marker-present behavior is byte-identical to today, so this ships opt-in.

Tests

Six new unit tests on reconcile_decision cover drift, match, tag-marker convergence, no-version skip, disabled-flag skip, and legacy marker parsing. cargo fmt --check, cargo clippy --all-targets --all-features -D warnings, and cargo test --lib (255) pass.

The behavior was proven against a live rig first: a version-matched re-pull pass refreshed 30 stale namespaces with zero errors and was a full no-op on the second run.

Fixes MOT-4187

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
workers	Ready	Preview, Comment	Jul 24, 2026 10:47am
workers-tech-spec	Ready	Preview, Comment	Jul 24, 2026 10:47am

[github-actions]

skill-check — worker

0 verified, 48 skipped (no docs/).

Layer	Result
structure	✓
vale	✓
ai	✓
render	✓

Four for four. Nicely done.

[coderabbitai]

Warning

Review limit reached

@rohitg00, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 6 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 8639a8ff-f35a-443c-88eb-8a24098da883

📥 Commits

Reviewing files that changed from the base of the PR and between 60b17f6 and f28b92f.

📒 Files selected for processing (4)

• iii-directory/README.md
• iii-directory/src/config.rs
• iii-directory/src/functions/download.rs
• iii-directory/src/main.rs

📝 Walkthrough

Walkthrough

Adds the auto_refresh setting, version fields to completion markers, version-aware reconciliation, worker update event handling, centralized worker version lookup, and tests and documentation covering refresh behavior.

Changes

Skill refresh lifecycle

Layer / File(s)	Summary
Refresh configuration and documentation iii-directory/src/config.rs, iii-directory/README.md	Adds auto_refresh, defaulting to false, and documents hot reload, worker updates, version comparison, and legacy marker convergence.
Versioned completion markers and reconciliation iii-directory/src/functions/download.rs	Records concrete versions in completion markers and refreshes when installed and recorded versions differ; tests cover matching, drift, missing versions, and legacy markers.
Worker events and boot reconciliation wiring iii-directory/src/main.rs	Handles worker add and update events, resolves installed versions through worker::list, reuses list parsing, and passes auto_refresh into reconciliation.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Worker
  participant WorkerEventHandler
  participant IIIClient
  participant ReconcileDecision
  participant SkillDownload
  Worker->>WorkerEventHandler: emit add or update event
  WorkerEventHandler->>IIIClient: resolve installed version when needed
  IIIClient-->>WorkerEventHandler: return worker version
  WorkerEventHandler->>ReconcileDecision: select latest or pinned VersionSpec
  ReconcileDecision->>SkillDownload: download or refresh skill bundle

Loading

Suggested labels: no-ticket

Suggested reviewers: andersonleal, guibeira

Poem

I’m a rabbit with markers tucked neat in a row,
Comparing versions wherever they go.
An update arrives—off the bundle will fly,
Old markers converge as the fresh files hop by.
Auto-refresh now keeps every skill bright!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: version-aware skill reconciliation in iii-directory.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/directory-version-reconcile

---

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.}