Peter Steinberger
1ea2640f54
* refactor(state): make cron and subagent rows JSON-canonical * refactor(state): make gateway origin device tokens canonical at v13 The lazy ensure predates the table joining the canonical schema; at the v13 bump the schema owns creation, so the feature-local DDL, WeakSet dedupe, and lazy-list entry retire. The legacy-file guard the ensure carried stays at each call site. * test: drop obsolete lazy-ensure coverage for origin device tokens The table is canonical at v13; same-version lazy creation no longer exists to protect. Origin CRUD, isolation, and rotation coverage remains in the surviving cases. * refactor(state): fold installed_plugin_index into config_machine_state The singleton index row becomes one JSON value under plugins.installedIndex with its rollback-fencing revision inside the value; reads, CAS restore, and the lease-held write transactions use direct Kysely on config_machine_state so the state_leases assertion stays in-transaction. The v13 migration imports the row and drops the table; the additive workspace_dir entry folds with it. Doctor guidance, docker staging, and the e2e probes name the machine-state row. * refactor(state): merge workspace_attestations into workspace_setup_state One row per workspace now carries both setup milestones and the attestation clock: nullable setup columns represent attestation-only workspaces (replaceWorkspaceAttestation can precede any setup write) and setupExists derives from a non-null version. The bootstrap-hash FK repoints to the merged table; migration receipts keep the historical workspace_attestations discriminator string. The v13 migration grows and rebuilds the table, merges attestation rows (orphans without a path alias drop — their hashes re-derive at the next bootstrap attestation), and the consolidation kind is renamed state-consolidation-v13 to cover the batch. * test(state): cover the workspace merge and consolidation fallout The v12-to-v13 regression seeds merged, attestation-only, and orphan attestation workspaces; the 13-to-12 downgrade fixture recreates workspace_attestations and installed_plugin_index from the folded data; the fold-in migration gates the additive workspace_dir column for pre-additive rows; the workspace merge now triggers on the setup table's own shape so stable-era databases without an attestations table still reshape; the consolidation applied-message covers the batch. * refactor(state): fold shared auth profile singletons into config_machine_state The shared-state auth_profile_stores/auth_profile_state rows (fixed key 'shared') become authProfiles.store/authProfiles.state machine-state values; the agent-DB tables of the same names are untouched. Git-backup redaction moves from table-drop to the authProfiles. secret prefix with seeded-secret absence proof; migration receipts keep the historical table-name discriminators; the shared-auth relocation and receipt verification project the KV cells back to the receipt-era row shapes so persisted digests stay byte-compatible. mcp_oauth_stores stays a table — its multi-key fold is a named follow-up. * test(state): finish shared-auth fold coverage and annotate boundary casts Auth seeders and assertions across the e2e/scripts/secrets suites target the authProfiles machine-state cells; the v12-to-v13 regression proves payload-byte fidelity, non-shared-row drop, and insert-if-absent precedence; the downgrade fixture recreates and repopulates both v12 tables. Boundary type assertions in the plugin-index store carry SAFETY invariants per the ratchet. * chore: shrink assertion-safety baseline for plugin-index store * refactor(doctor): delete the dead onboarding-recommendations migration Its input — the unscoped 'primary' onboarding row — existed only between9a93a52a8aand473962b7de, a two-day beta window; no shipped stable can produce it and the runtime table folded away at v12. The audit backup list keeps recognizing system-agent.jsonl artifacts because beta installs that ran that import may still carry its backups. * docs: sync the 13-to-12 downgrade example with the executable fixture * style: format the synced downgrade example * style: drop unused import and duplicate union constituent * fix(state): keep orphan attestations across the v13 workspace merge The merged workspace_setup_state required a workspace path, but legacy orphan hashed-key attestations never recorded one. workspace_path is now nullable (setup rows still enforce it via CHECK), the v13 migration and the doctor file import keep orphans with a NULL path that heals on the next live access, and the 13-to-12 downgrade keeps attestation-owned hashes. Doctor test seeds move to the folded KV row. * perf(state): retire unused cron indexes * fix(state): preserve v13 migration recovery * fix(state): preserve v12 lazy-table upgrade * docs(state): document v13 auth relocation --------- Co-authored-by: Vincent Koc <vincentkoc@ieee.org>
OpenClaw macOS app (dev + signing)
Quick dev run
# from repo root
scripts/restart-mac.sh
Options:
scripts/restart-mac.sh --no-sign # fastest dev; ad-hoc signing (TCC permissions do not stick)
scripts/restart-mac.sh --sign # force code signing (requires cert)
scripts/restart-mac.sh --background-only # keep services running without automatic windows
--background-only suppresses first-run onboarding, update and CLI prompts, and
the --chat/--dashboard auto-open helpers. Pairing, control-channel, and Mac
node services still start. It also keeps GUI-owned onboarding and saved Gateway
profile Keychain state cold, so a signer or ACL transition cannot raise a
SecurityAgent prompt during unattended work. The primary Gateway route still
comes from the normal environment/config endpoint. Combine it with
--attach-only when an external process owns the local Gateway.
App profiles
Launch a fully isolated app instance with the same profile name used by the CLI:
OPENCLAW_PROFILE=work /Applications/OpenClaw.app/Contents/MacOS/OpenClaw
Profile names use 1–64 lowercase letters, numbers, underscores, or hyphens and
must start with a letter or number. default selects the normal app; gateway,
mac, and node are reserved LaunchAgent identities.
scripts/restart-mac.sh intentionally rejects named profiles because its
packaging cleanup is host-global. Build/package normally, then launch the named
profile directly with the command above.
A named profile keeps state in ~/.openclaw-<name>, uses its own app defaults,
Keychain services, duplicate-instance lock, and the CLI-managed Gateway service
ai.openclaw.<name>. Unless config or environment selects a port, each profile
derives a stable port in the profile 20000...59999 range. The app does not
install or modify the host-global Mac node
service or OpenClaw login item while a profile is active. The runtime child node
still runs in process as usual. App relocation, Sparkle updates, and post-update
service repair are disabled in profile mode; update the installed app through
the normal default-profile workflow.
Packaging flows
Development bundle (signed but not notarized):
scripts/package-mac-app.sh
This creates dist/OpenClaw.app and signs it via scripts/codesign-mac-app.sh.
It is not a distribution artifact. For a notarized app ZIP and DMG, use:
scripts/package-mac-dist.sh
For an unattended Peekaboo elevation host, use the closed Foundation signing
profile and source-addressed ZIP workflow. package is an internal release
operator command: it requires the OpenClaw Foundation signing identity and
notarization credentials, and its archive is not a general-download artifact.
scripts/mac-elevation-host.sh package \
--peekaboo-source-commit <full-peekaboo-sha>
cd dist/elevation-host
export PREFIX="OpenClaw-<full-openclaw-sha>-Peekaboo-<full-peekaboo-sha>-stable"
export INSTALLER_SHA256="<authenticated-installer-sha256>"
export RECEIPT_SHA256="<authenticated-receipt-sha256>"
[[ "$(shasum -a 256 "$PREFIX-installer.sh" | awk '{print $1}')" == "$INSTALLER_SHA256" ]] || exit 1
shasum -a 256 -c "$PREFIX.zip.sha256"
shasum -a 256 -c "$PREFIX-installer.sh.sha256"
./"$PREFIX-installer.sh" verify \
--archive "$PREFIX.zip" \
--receipt "$PREFIX.json" \
--receipt-sha256 "$RECEIPT_SHA256"
./"$PREFIX-installer.sh" migration-plan \
--migrate-launch-agent "$HOME/Library/LaunchAgents/ai.openclaw.node.plist"
./"$PREFIX-installer.sh" install \
--archive "$PREFIX.zip" \
--receipt "$PREFIX.json" \
--receipt-sha256 "$RECEIPT_SHA256" \
--migrate-launch-agent "$HOME/Library/LaunchAgents/ai.openclaw.node.plist"
./"$PREFIX-installer.sh" status --state-dir "<existing-state-dir>"
The elevation package is ZIP-only, notarized and stapled, contains exactly
OpenClaw.app, omits Apple Events entitlements, records an immutable receipt,
and verifies a freshly extracted copy. The same source-addressed artifact set
includes a portable installer copied from that exact Git commit plus separate
archive and installer checksum files. Transfer the archive, receipt, portable
installer, and both checksums; the target Mac does not need a source checkout.
The release operator must deliver the receipt SHA-256 through the authenticated
handoff alongside the separately authenticated installer digest. verify uses
that receipt digest to select the approved archive and then checks its signer,
entitlements, architectures, and both source revisions. The portable installer
is not covered by the app's code signature, so this explicit two-digest operator
handoff remains part of the internal workflow's trust boundary.
Installation requires an existing app-readable remote Gateway config and a
paired macOS node identity in the selected state directory. Use
migration-plan before changing a CLI-managed node LaunchAgent. For a currently
running background app with no LaunchAgent, use the explicit
--adopt-running-app plan/install option instead. The installer copies no token
or password: it preserves only the state and config ownership paths, then
requires the same node identity to reconnect as openclaw-macos/node with the
new app version and computer-use capabilities before committing. Installation owns the separate
ai.openclaw.mac.elevation-host launchd job with RunAtLoad and KeepAlive.
It refuses to replace or race the ordinary ai.openclaw.mac Launch at login
job. recover restores the recorded prior bundle after a failed cutover;
uninstall removes only the elevation job and preserves the app, state,
Keychain, TCC, and recovery receipt. Installation exits successfully once the
launchd-owned process is both Bridge-ready and reconnected to the Gateway as the
expected computer-use node. Missing TCC remains a degraded status result until
the required grants are present. Managed upgrades use generation-unique plist and
receipt backups. Recovery preserves the replaced app in a unique evidence directory
and restores the prior install receipt, so status and a same-artifact reinstall
remain valid after rollback.
Signing behavior
Auto-selects identity (first match):
- Developer ID Application
- Apple Distribution
- Apple Development
- first available identity
If none found:
- errors by default
- set
ALLOW_ADHOC_SIGNING=1orSIGN_IDENTITY="-"to ad-hoc sign
Team ID audit (Sparkle mismatch guard)
After signing, we read the app bundle Team ID and compare every Mach-O inside the app. If any embedded binary has a different Team ID, signing fails.
Skip the audit:
SKIP_TEAM_ID_CHECK=1 scripts/package-mac-app.sh
Library validation workaround (dev only)
If Sparkle Team ID mismatch blocks loading (common with Apple Development certs), opt in:
DISABLE_LIBRARY_VALIDATION=1 scripts/package-mac-app.sh
This adds com.apple.security.cs.disable-library-validation to app entitlements.
Use for local dev only; keep off for release builds.
Useful env flags
SIGN_IDENTITY="Apple Development: Your Name (TEAMID)"ALLOW_ADHOC_SIGNING=1(ad-hoc, TCC permissions do not persist)CODESIGN_TIMESTAMP=off(offline debug)DISABLE_LIBRARY_VALIDATION=1(dev-only Sparkle workaround)SKIP_TEAM_ID_CHECK=1(bypass audit)