AlphaClaw macOS Compatibility, building on pr-4-macos

[diazMelgarejo]

Summary

• macOS bin-path routing: Extracts getBinPath() into lib/platform.js — darwin routes to ~/.local/bin (user-writable, no sudo), Linux keeps /usr/local/bin with managed fallback.
• Read-only onboarding: New readOnlyMode flow attaches AlphaClaw to an existing local OpenClaw setup without modifying any config files, writing git state, or touching the gateway proxy config.
• sanitizeOpenclawConfig: Ensures every provider in openclaw.json has models: [], preventing the OpenClaw gateway JSON-schema crash that causes a 30s startup timeout.
• Rebase on 0.9.3: Merges upstream/main — preserves all new route structure, SSE /api/events/status, buildStatusPayload() refactor, and bundler-style frontend imports while keeping the read-only onboarding invariants.
• Test fixes (merge conflict residue): getSystemCronStatus missing deps arg, duplicate ensureGatewayProxyConfig outside read-only guard, ensureManagedExecDefaults modifying config in read-only mode, and api.test.js body expectation missing readOnlyMode.

Test plan

• All 538 tests pass: npx vitest run
• getBinPath() unit tests: 4 passing
• sanitizeOpenclawConfig() unit tests: 7 passing
• Read-only onboarding: passes without writing openclaw.json
• macOS: alphaclaw start installs binary to ~/.local/bin without sudo
• macOS: { readOnlyMode: true } to /api/onboard completes without rewriting existing config

---

Branch pr-4-macos (pushed from diazMelgarejo/AlphaClaw)

Commit	Change
ad2325f	Merge upstream/main (0.9.3) into pr-4-macos: 9 conflicts resolved, read-only onboarding preserved
3bbf43d	fix(macos): lib/platform.js with getBinPath(), 4 tests
3d99697	fix(platform): code review fixes — fs top-level, homedir arrow fn, import kSystemBinDir, Linux prependPathEntry
4d04616	fix(gateway): sanitizeOpenclawConfig() in openclaw-config.js, 5 tests, wired into bin/alphaclaw.js
61c8284	fix(gateway): harden against null providers, array-typed providers, revert let cfg — 7 tests total

Full suite: 535 passed, 3 failures (after merging main to pr-4-macos)

---

Fixed: post main -> pr-4-macos

Failure	Root cause	Fix
routes-system.test.js — "reports running gateway status"	getSystemCronStatus() called with no args at line 501; needs deps {fs, openclawDir, platform}	Changed to readSystemCronConfig() (the local wrapper that captures deps)
routes-onboarding.test.js — "supports read-only onboarding"	Two issues from merge: (1) duplicate ensureGatewayProxyConfig call outside the !readOnly guard; (2) ensureManagedExecDefaults (added by upstream) runs unconditionally and writes to openclaw.json	Removed the duplicate call; guarded ensureManagedExecDefaults behind !validatedReadOnlyMode
tests/frontend/api.test.js — "runOnboard sends vars and modelKey"	Test expected old body without readOnlyMode; our PR added readOnlyMode to the payload	Updated expected body to include readOnlyMode: false

All 3 failures were merge conflict residue — the fixes preserve the correct invariant that read-only onboarding must not write to openclaw.json or call ensureGatewayProxyConfig.

[diazMelgarejo]

No open test gaps remain from the original checklist.

a05cbe9 — fix: return contract

-   return status.installed || (status.platform === "darwin" && status.enabled);
+   const finalStatus = getSystemCronStatus({ fs, openclawDir, platform });
+   return finalStatus.installed;

startManagedScheduler() sets kSchedulerState.active synchronously, so the re-read sees the correct runtime state immediately. getSystemCronStatus was already imported; one import line added for it.

7641a7f — test: Linux install path

Calls installHourlyGitSyncCron() with platform: "linux", then asserts kSystemCronPath exists in the memory-fs, contains the default schedule string, and getSystemCronStatus() returns { installed: true, installMethod: "system_cron" }.

a7bd4b2 — test: darwin disable → re-enable

Three phases against the same memory-fs:

1. Install → installed: true
2. stopManagedScheduler() → installed: false
3. Re-install → installed: true again

4cba0d8 — test: return value semantics

Asserts result === getSystemCronStatus().installed for both darwin and linux. If the broadened installed || (darwin && enabled) expression ever comes back, these tests break as soon as enabled is true but installed is still false.

[chrysb]

Thank you! I will inspect this over the weekend.