fix(core): fall back to packaged worker registry

[rafaelscosta]

Summary

• Fixes service-registry bootstrap for CLI runs outside an installed project cwd.
• Keeps explicit custom registry paths strict, while default loading falls back from cwd registry to the packaged registry.
• Adds unit and CLI regression coverage for the packaged-registry fallback.

Issue

Part of #621: bootstrap resilience / safe lazy-loading of the registry.

Validation

• Reproduced before fix: node bin/aiox.js workers list --count from a temp cwd failed with ENOENT for .aiox-core/core/registry/service-registry.json.
• After fix: same command from temp cwd returns Total: 203 workers.
• node -c .aiox-core/core/registry/registry-loader.js: pass
• node -c bin/aiox.js: pass
• jest tests/core/registry-loader.test.js tests/unit/cli.test.js --runInBand: 53 passed
• npm run generate:manifest: pass
• npm run validate:manifest: pass
• git diff --check: pass
• npm run lint: pass, 0 errors / 114 baseline warnings
• npm run typecheck: pass
• node scripts/validate-package-completeness.js: 34/34 passed
• node bin/utils/validate-publish.js: pass, 4199 packed files
• npm test -- --runInBand --forceExit: 330 suites passed, 11 skipped; 8346 tests passed, 149 skipped

Notes

The IDS hook repeatedly generated volatile .aiox-core/data/entity-registry.yaml changes during tests/push. Those were restored because they were generated noise and, in one incremental pass, mapped the wrong registry-loader path.

Summary by CodeRabbit

• New Features

  • Registry loader now supports fallback search across multiple locations when the primary registry is unavailable.

• Improvements

  • The resolved registry path is recorded and exposed in metrics for better diagnostics.
  • CLI command stability improved when run from outside a project directory.

• Tests

  • Expanded coverage for registry resolution, caching behavior, and CLI invocation scenarios.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
aiox-core	Ready	Preview, Comment	May 8, 2026 5:55am

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: d847f8ba-d1e9-4782-81f3-6fb83b227bb2

📥 Commits

Reviewing files that changed from the base of the PR and between ae6a103 and 38706e6.

📒 Files selected for processing (1)

• tests/unit/cli.test.js

---

Walkthrough

ServiceRegistry now supports multiple candidate registry locations with automatic fallback behavior. When no explicit registry path is provided, the loader attempts the current working directory registry first, then falls back to the packaged registry. The resolved path is tracked and exposed via metrics and state management methods.

Changes

Registry Path Resolution with Fallback

Layer / File(s)	Summary
Path Resolution Helpers .aiox-core/core/registry/registry-loader.js	Constants define registry search locations (cwd and packaged); deduplication utility prevents duplicate path candidates.
Multi-Path Registry Reader .aiox-core/core/registry/registry-loader.js	New readRegistryFile() iterates candidate paths, returns first success with path, or throws aggregated error if all fail.
ServiceRegistry State & Load .aiox-core/core/registry/registry-loader.js	New instance field resolvedRegistryPath tracks loaded registry path; load() accepts explicit registryPath or uses default paths for fallback.
Error Handling & Metrics .aiox-core/core/registry/registry-loader.js	Multi-path errors propagate unwrapped; getMetrics() includes resolved registry path; clearCache() resets resolvedRegistryPath.
Test Coverage: Baseline tests/core/registry-loader.test.js	Imports getDefaultRegistryPaths; constructor assertion updated to verify resolvedRegistryPath null by default.
Test Coverage: Path Resolution tests/core/registry-loader.test.js	New tests verify fallback when cwd registry missing and explicit path behavior without fallback.
Test Coverage: State Management tests/core/registry-loader.test.js	Cache-clear tests updated to assert resolvedRegistryPath reset to null.
Integration Test: CLI tests/unit/cli.test.js	New test spawns workers list --count from temp directory, verifies packaged registry loads successfully.
Manifest Sync .aiox-core/install-manifest.yaml	Timestamp and file hash/size entries updated.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Suggested labels

area: core, area: cli, type: test

Suggested reviewers

• oalanicolas
• Pedrovaleriolopez

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix(core): fall back to packaged worker registry' directly summarizes the main change: enabling a fallback mechanism from the current working directory registry to the packaged registry when loading the service registry outside an installed project.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch devops/issue-621-registry-bootstrap-fallback-20260508

---

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

[github-actions]

📊 Coverage Report

Coverage report not available

📈 Full coverage report available in Codecov

---

Generated by PR Automation (Story 6.1)

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tests/unit/cli.test.js`:
- Around line 120-127: The test is flaky because registry-loader's console.warn
writes to stderr when load >500ms, so change the brittle assertion
expect(errors).toBe('') inside the child.on('close' ...) callback to allow
warnings but still fail on real errors—e.g., replace it with a negative match
like expect(errors).not.toMatch(/Error|ERROR/) (or simply remove the assertion
entirely and rely on expect(code).toBe(0)); locate the assertion by finding the
child.on('close' handler and the expect(errors).toBe('') call and update it
accordingly to ignore benign console.warn output from registry-loader.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 3c1faa68-2434-4dc8-a110-7e335c88d578

📥 Commits

Reviewing files that changed from the base of the PR and between 6604086 and ae6a103.

📒 Files selected for processing (4)

• .aiox-core/core/registry/registry-loader.js
• .aiox-core/install-manifest.yaml
• tests/core/registry-loader.test.js
• tests/unit/cli.test.js