macOS arm64 clean install: Homebrew prerequisites, darwin pins, launchd agents (brew-services semantics), embedding acceptance, recording-tooling CI

.gitignore

@@ -15,6 +15,7 @@ node_modules/
 *.jsonl
 adoption/hosts/*.json
 !adoption/hosts/example.json
+!adoption/hosts/macos-example.json
 
 # Generated public explorer (scripts/build_ecosystem.py --write); rebuilt
 # locally or downloaded from the publish-catalog.yml release artifact/

adoption/bootstrap.md

@@ -130,7 +130,22 @@ nothing on that page has been executed on a Mac; see
    `id`, `kind`, `component_ids`, `observed_at_utc`, `status`, `claim`, `scope`,
    `data`. Distinguish `native_cli_e2e` (an actual command ran on this host)
    from `source_review` (documented, not executed) and from a candidate that
-   has neither.
+   has neither. `scripts/host_receipts.py` (this same step's own recording
+   tool, plus `scripts/component_matrix.py`, `scripts/new_host_grand_list.py`,
+   `tools/sota-convergence/build_verdicts.py`,
+   `scripts/validate_convergence.py` and `scripts/release_due.py`) needs
+   **Python 3.9 or newer**: every one of those scripts parses under the
+   Python 3.9 grammar and uses `from __future__ import annotations`, and this
+   is exercised directly, not merely declared -- a macOS CI job runs the
+   recording smoke below against both the manifest-pinned Python line and the
+   host's own system `/usr/bin/python3` (macOS ships 3.9.6 there by default,
+   the same floor this bullet declares; see
+   [the macOS page](platforms/macos-arm64.md#recording-and-verdict-scripts)).
+   Linux/WSL2 hosts use the manifest-pinned line (`python@3.13` on macOS,
+   already required by step 1's prerequisites); this floor exists so a host
+   that has not yet installed the pinned line -- or one recording a receipt
+   with only the OS-bundled interpreter -- still has a working
+   `host_receipts.py`.
 
 Every step above is guidance; running or validating this page does not itself
 execute anything (`adoption/lifecycle.md`, "This guide supplies future-host

adoption/hosts/macos-example.json

@@ -0,0 +1,13 @@
+{
+  "HOME": "/Users/example",
+  "ECO_ROOT": "/Users/example/.local/share/codex-ecosystem",
+  "PROJECT_ROOT": "/Users/example/code/agent-lab",
+  "HOST_PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
+  "CODE_INDEX_PATH": "/Users/example/.code-index",
+  "OTEL_ENDPOINT": "127.0.0.1:14318",
+  "AI_MEMORY_URL": "127.0.0.1:49374",
+  "QDRANT_URL": "127.0.0.1:16333",
+  "EMBED_URL": "127.0.0.1:8232",
+  "EMBED_MODEL_PATH": "/Users/example/.local/share/codex-ecosystem/state/models/embeddinggemma-300M-Q8_0.gguf",
+  "HARDWARE_PROFILE_ID": "macos-arm64-48gb-projected"
+}

adoption/launchd/com.native-stack.ai-memory.plist.template

@@ -0,0 +1,61 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!--
+  Drafted, not run: no launchd agent from this directory has been
+  bootstrapped, kickstarted or booted out on any Mac (adoption/platforms/
+  macos-arm64.md, "What a hosted run proves"). Render with
+  tools/adoption/render_launchd.py before use; lint with
+  adoption/launchd/launchd-agents.sh lint before ever bootstrapping it.
+
+  Mirrors this profile's Linux/WSL2 ai-memory serve unit, given a transport
+  flag of http and a bind flag of AI_MEMORY_URL (recipes/README.md,
+  docs/foundation-stack.md), invoking the same bin/ai-memory symlink
+  adoption/bootstrap-macos.sh places on PATH. Hooks install, MCP
+  registration and any managed run remain separate macOS steps with no
+  receipt yet (adoption/pins-macos-arm64.json, ai-memory install_note).
+  Round 3j (Codex P2 thread 5): the workspace flag (local) and project
+  flag (native-agent-stack) below match the exact selected native
+  recipe's own serve invocation, quoting recipes/README.md:244: ai-memory
+  serve with a transport flag of http, an enable-web flag, a bind flag of
+  127.0.0.1:49374, a workspace flag of local and a project flag of
+  native-agent-stack (docs/foundation-stack.md:51-52 documents the same
+  workspace/project scope). Without these two flags, this agent would
+  serve with no workspace or project scope at all, unlike every other
+  documented ai-memory invocation in this project: write-page, search and
+  read-page all pass this same workspace/project pair too
+  (recipes/README.md:263-267).
+-->
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.native-stack.ai-memory</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>${ECO_ROOT}/bin/ai-memory</string>
+        <string>--data-dir</string>
+        <string>${HOME}/.local/share/ai-memory</string>
+        <string>serve</string>
+        <string>--transport</string>
+        <string>http</string>
+        <string>--bind</string>
+        <string>${AI_MEMORY_URL}</string>
+        <string>--workspace</string>
+        <string>local</string>
+        <string>--project</string>
+        <string>native-agent-stack</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/opt/homebrew/bin:${ECO_ROOT}/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+    </dict>
+    <key>StandardOutPath</key>
+    <string>${ECO_ROOT}/state/logs/com.native-stack.ai-memory.out.log</string>
+    <key>StandardErrorPath</key>
+    <string>${ECO_ROOT}/state/logs/com.native-stack.ai-memory.err.log</string>
+</dict>
+</plist>

adoption/launchd/com.native-stack.llama-embed.plist.template

@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!--
+  Drafted, not run: no launchd agent from this directory has been
+  bootstrapped, kickstarted or booted out on any Mac (adoption/platforms/
+  macos-arm64.md, "What a hosted run proves"). Render with
+  tools/adoption/render_launchd.py before use; lint with
+  adoption/launchd/launchd-agents.sh lint before ever bootstrapping it.
+
+  Runs the 24 GB default from adoption/platforms/macos-arm64.md's "Embedding
+  backend decision": llama-server given an embedding flag and a port flag of
+  8232, serving embeddinggemma-300M-Q8_0 (768 dimensions), a distinct port
+  from the Linux/WSL2 RAG endpoint at 8231, so a macOS host never presents a
+  768-dim response where 2048-dim is expected. Invokes the bin/llama-server
+  wrapper adoption/bootstrap-macos.sh installs (it exports DYLD_LIBRARY_PATH
+  itself, see the llama-cpp install_note in adoption/pins-macos-arm64.json),
+  so this plist carries no DYLD_LIBRARY_PATH of its own. Round 3h: -m names
+  the model file bootstrap-macos.sh's dedicated install_embed_model step
+  downloads and sha256-verifies (adoption/pins-macos-arm64.json's separate
+  models[] section, not tools[]); without it, KeepAlive would restart this
+  agent in a loop forever without ever actually serving embeddinggemma (the
+  defect a 2026-09-23 readiness audit found: this template ran with no model
+  argument at all). EMBED_MODEL_PATH is a host value like ECO_ROOT
+  (adoption/hosts/<host>.json, or an explicit override), resolved to the
+  model's actual path on disk.
+-->
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.native-stack.llama-embed</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>${ECO_ROOT}/bin/llama-server</string>
+        <string>--embedding</string>
+        <string>--port</string>
+        <string>8232</string>
+        <string>-m</string>
+        <string>${EMBED_MODEL_PATH}</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/opt/homebrew/bin:${ECO_ROOT}/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+    </dict>
+    <key>StandardOutPath</key>
+    <string>${ECO_ROOT}/state/logs/com.native-stack.llama-embed.out.log</string>
+    <key>StandardErrorPath</key>
+    <string>${ECO_ROOT}/state/logs/com.native-stack.llama-embed.err.log</string>
+</dict>
+</plist>

adoption/launchd/com.native-stack.qdrant.plist.template

@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!--
+  Drafted, not run: no launchd agent from this directory has been
+  bootstrapped, kickstarted or booted out on any Mac (adoption/platforms/
+  macos-arm64.md, "What a hosted run proves"). Render with
+  tools/adoption/render_launchd.py before use; lint with
+  adoption/launchd/launchd-agents.sh lint before ever bootstrapping it.
+
+  Mirrors the systemd user-scoped unit this profile's Linux/WSL2 host runs
+  for qdrant (adoption/lifecycle.md, recipes/README.md's qdrant row: the
+  qdrant binary given a config-path flag and disable-telemetry flag),
+  invoking the same bin/qdrant symlink adoption/bootstrap-macos.sh places on
+  PATH so this plist survives a version bump without editing. WorkingDirectory
+  gives qdrant's own relative default paths (its config's storage_path is
+  supplied separately, at install time, not baked into this template) a
+  stable directory to resolve against, mirroring a systemd unit's own
+  WorkingDirectory=; launchd-agents.sh's install subcommand creates it.
+-->
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.native-stack.qdrant</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>${ECO_ROOT}/bin/qdrant</string>
+        <string>--config-path</string>
+        <string>${ECO_ROOT}/config/qdrant.yaml</string>
+        <string>--disable-telemetry</string>
+    </array>
+    <key>WorkingDirectory</key>
+    <string>${ECO_ROOT}/state/qdrant</string>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/opt/homebrew/bin:${ECO_ROOT}/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+    </dict>
+    <key>StandardOutPath</key>
+    <string>${ECO_ROOT}/state/logs/com.native-stack.qdrant.out.log</string>
+    <key>StandardErrorPath</key>
+    <string>${ECO_ROOT}/state/logs/com.native-stack.qdrant.err.log</string>
+</dict>
+</plist>