fix(persona-kit): defer @relayfile/local-mount import to call site

[khaliqgant]

Summary

mount.ts imported @relayfile/local-mount at module top, which transitively imports @parcel/watcher and triggers a per-platform native-binary load at module evaluation time. That broke every server-side consumer that just wanted to call parsePersonaSpec — most visibly the cloud deploy POST handler in AWS Lambda.

Concrete blast

User ran agentworkforce deploy --no-prompt --harness-source oauth against agentrelay.com/cloud. After all the workspace/integrations/harness checks passed, the bundle upload landed at cloud's deploy POST, which does:

mod = await import("@agentworkforce/persona-kit");

…to validate the uploaded persona. The Lambda runtime is linux-x64-glibc, but OpenNext's dep-tracer didn't bundle @parcel/watcher's optional native prebuild (@parcel/watcher-linux-x64-glibc). Result:

500 {"error":"Persona validation is unavailable: @agentworkforce/persona-kit could not be loaded",
     "code":"persona_kit_unavailable",
     "details":[{"path":"persona","message":"No prebuild or local build of @parcel/watcher found.
        Tried @parcel/watcher-linux-x64-glibc. ..."}]}

The fix

@parcel/watcher is a real dep for the CLI/runtime path (auto-sync, watch mode). It is not a dep for the server-side validation path. The right thing is to load it only when a mount is actually being applied.

mount.ts now defers the @relayfile/local-mount import via a small loadCreateMount() helper that's awaited inside applyPersonaMount. At module-evaluation time mount.ts no longer touches the watcher; at call time, mount consumers see no behavior change. The barrel re-export from index.ts stays intact — no API breakage.

Verified

• 170/170 persona-kit tests pass.
• Full repo pnpm run test — 544 tests across 8 packages, all pass.
• Local probe (dynamic-import the built dist + parsePersonaSpec(...)): succeeds with no @parcel/watcher load.

Once this publishes and the user retries their proactive-agents deploy, cloud's import('@agentworkforce/persona-kit') should succeed and parsePersonaSpec should run to completion — clearing the last known blocker on the end-to-end customer flow.

Test plan

• pnpm -F @agentworkforce/persona-kit run test — 170/170 pass
• pnpm run typecheck — all packages clean
• pnpm run test — 544/544 pass repo-wide
• Probe: import('@agentworkforce/persona-kit') + parsePersonaSpec does not trigger @parcel/watcher on darwin-arm64

🤖 Generated with Claude Code

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 8d57a276-2b9d-49fc-942c-537291b3241e

📥 Commits

Reviewing files that changed from the base of the PR and between 97a800b and 6c6a142.

📒 Files selected for processing (1)

• packages/persona-kit/src/mount.ts

---

📝 Walkthrough

Walkthrough

packages/persona-kit/src/mount.ts replaces a static top-level import of @relayfile/local-mount with a dynamic import helper function loadCreateMount(). The applyPersonaMount function now calls this async helper at mount time to obtain createMount, deferring native binary loading from module-evaluation time to mount-application time.

Changes

Deferred import refactor

Layer / File(s)	Summary
Lazy-load createMount for deferred native binary initialization packages/persona-kit/src/mount.ts	The static top-level import of @relayfile/local-mount is replaced with an internal loadCreateMount() async helper that dynamically imports the module and returns createMount. applyPersonaMount now calls await loadCreateMount() at mount-application time instead of using a statically imported binding.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• AgentWorkforce/workforce#81: Adds mount.test.ts coverage for applyPersonaMount's mount-policy and error behaviors, directly testing the function modified in this PR.
• AgentWorkforce/workforce#56: Bumps the @relayfile/local-mount dependency version, directly related to the module being dynamically imported in this change.

Suggested reviewers

• willwashburn

Poem

🐇 Hops through hoops to defer the load,
Native binaries need not road,
Lazy imports light the way,
Until the mount gets called—hooray! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: deferring the @relayfile/local-mount import to the call site, which directly addresses the core fix in the changeset.
Description check	✅ Passed	The description thoroughly explains the problem (native binary loading at module evaluation time breaking server-side validation), the solution (deferred import via loadCreateMount helper), and provides concrete verification details.
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.

_{✏️ 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 fix-persona-kit/defer-local-mount-import

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

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

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 2 additional findings.