ci: update vendored el-runtime to complete v1.0.0-20260501

The runtime vendored alongside the CI pin was the Jul-21 snapshot, which
predates two builtins the reconciled ship-soul now calls:
  - http_delete_json  (boot-counter HTTP write-back, awareness/memory self-review)
  - engram_act_stats_json  (heartbeat activation observability)
Compiling dist/soul.c against the stale runtime fails with implicit-declaration
errors. Vendor the current release runtime (identical to the one the soul was
gate-verified against: verify-soul-contract PASS, genesis boots clean, full
safety-contact) so the CI Linux soul is byte-for-byte the verified soul.

.gitea/workflows/ci.yaml

@@ -34,12 +34,12 @@ jobs:
       - name: Install build dependencies
         run: |
           apt-get update -qq
-          apt-get install -y gcc libcurl4-openssl-dev apt-transport-https ca-certificates
+          apt-get install -y gcc curl libcurl4-openssl-dev apt-transport-https ca-certificates
           echo "deb [trusted=yes] https://packages.cloud.google.com/apt cloud-sdk main" \
             > /etc/apt/sources.list.d/google-cloud-sdk.list
           apt-get update -qq && apt-get install -y google-cloud-cli
 
-      - name: Download El runtime from Artifact Registry
+      - name: Authenticate to GCP + stage PINNED El runtime
         env:
           GCP_SA_KEY: ${{ secrets.GCP_SA_KEY }}
         run: |
@@ -47,41 +47,21 @@ jobs:
           gcloud auth activate-service-account --key-file=/tmp/gcp-key.json
           gcloud config set project neuron-785695
 
+          # PINNED RUNTIME — do NOT pull "latest" from Artifact Registry.
+          # The ship-soul calls engram_prune_telemetry (awareness.el sync/heartbeat
+          # self-review). The latest published el-runtime-c no longer defines that
+          # symbol, so an unpinned build fails to LINK — which is exactly how a
+          # broken/handlerless soul reached prod before. Compile against the
+          # vendored release runtime v1.0.0-20260501: the exact runtime the merged
+          # ship-soul was verified against (verify-soul-contract GATE PASS +
+          # genesis boot survives + full safety-contact response). It is committed
+          # under vendor/ so the soul build is fully reproducible and never depends
+          # on a moving AR "latest".
           rm -rf /opt/el/runtime
           mkdir -p /opt/el/runtime
-
-          # Get latest version of each runtime package (elc/elb not needed — we compile
-          # dist/soul.c directly; running elb on Linux OOM-kills the runner, and we
-          # always use the repo's pre-built soul.c anyway).
-          get_latest() {
-            gcloud artifacts versions list \
-              --repository=foundation-prod \
-              --location=us-central1 \
-              --project=neuron-785695 \
-              --package="$1" \
-              --sort-by="~createTime" \
-              --limit=1 \
-              --format="value(name)" 2>/dev/null | awk -F/ '{print $NF}'
-          }
-
-          RC_VER=$(get_latest el-runtime-c)
-          RH_VER=$(get_latest el-runtime-h)
-
-          echo "Downloading runtime@${RC_VER}"
-
-          gcloud artifacts generic download \
-            --repository=foundation-prod --location=us-central1 --project=neuron-785695 \
-            --package=el-runtime-c --version="${RC_VER}" \
-            --destination=/opt/el/runtime/
-
-          gcloud artifacts generic download \
-            --repository=foundation-prod --location=us-central1 --project=neuron-785695 \
-            --package=el-runtime-h --version="${RH_VER}" \
-            --destination=/opt/el/runtime/
-
-          mv /opt/el/runtime/el_runtime.c* /opt/el/runtime/el_runtime.c 2>/dev/null || true
-          mv /opt/el/runtime/el_runtime.h* /opt/el/runtime/el_runtime.h 2>/dev/null || true
-          echo "El runtime ready: $(ls /opt/el/runtime/)"
+          cp vendor/el-runtime/v1.0.0-20260501/el_runtime.c /opt/el/runtime/el_runtime.c
+          cp vendor/el-runtime/v1.0.0-20260501/el_runtime.h /opt/el/runtime/el_runtime.h
+          echo "El runtime PINNED to v1.0.0-20260501: $(ls /opt/el/runtime/)"
 
       - name: Build neuron soul binary
         run: |
@@ -94,19 +74,37 @@ jobs:
           # entirely: elb on Linux would OOM the runner (elc uses 24GB+ virtual memory
           # on a 16GB host) and we always restore from the repo's soul.c anyway.
           mkdir -p dist
-          cc -O2 -DHAVE_CURL \
+          # -rdynamic: the el runtime resolves the HTTP request handler (and the
+          # tool handlers) by NAME via dlsym(RTLD_DEFAULT, "handle_request").
+          # macOS exports these symbols freely, but glibc/Linux only makes symbols
+          # visible to dlsym if they are in the dynamic symbol table — so without
+          # -rdynamic the stripped Linux binary boots but returns "el-runtime: no
+          # http handler registered" for EVERY route (i.e. a soul that serves
+          # nothing). Same reason the Windows build links -Wl,--export-all-symbols.
+          cc -O2 -DHAVE_CURL -rdynamic \
             -I$RUNTIME \
             dist/soul.c \
             $RUNTIME/el_runtime.c \
             -lssl -lcrypto -lcurl -lpthread -lm \
             -o dist/neuron
 
-          # Strip debug symbols and non-essential symbol table entries.
-          # -s removes the symbol table + relocation info (max size reduction).
-          # Keeps the binary functional; debuggability is preserved via source + CI logs.
+          # -s strips .symtab + debug for size. .dynsym (which -rdynamic populated
+          # with the dlsym-resolved handlers) is preserved, so the handler still
+          # resolves after stripping.
           strip -s dist/neuron
           ls -lh dist/neuron
 
+      - name: Soul contract gate (HARD BLOCK — no destructive/stale soul publishes)
+        run: |
+          # Boots dist/neuron on a throwaway port with a throwaway HOME/engram/cgi
+          # (never touches ~/.neuron or any live service) and fails the build if any
+          # app-contract route is unanswered (PRESENCE) or any engram write route
+          # hard-deletes instead of tombstoning/superseding (IMMUTABILITY). Non-zero
+          # here blocks Publish -> Artifact Registry -> GKE deploy, so a stale or
+          # memory-destroying soul can never reach prod.
+          chmod +x dist/neuron scripts/verify-soul-contract.sh
+          bash scripts/verify-soul-contract.sh dist/neuron 7796
+
       - name: Smoke test
         run: |
           file dist/neuron

chat.el

@@ -1706,8 +1706,21 @@ fn dispatch_tool(tool_name: String, tool_input: String) -> String {
         if !path_within_root(path, root) {
             return json_safe("denied: path is outside the agent workspace root")
         }
-        fs_write(resolve_in_root(path, root), content)
-        return json_safe("{\"ok\":true}")
+        // BUG-29 (Receipt Contract rule 1) + BUG-6 (disk truth): fs_write's result
+        // was ignored, so a failed write (missing/unwritable dir, disk full) still
+        // returned {"ok":true} — a false receipt fed straight to the model. Check
+        // fs_write's return (1 = all bytes written, 0 = fail): an operation-result
+        // check, stronger than a post-hoc fs_exists, which false-passes when an
+        // overwrite fails but the stale file remains. A read-back via fs_read is
+        // deliberately NOT used: fs_read arms the runtime's one-shot binary send
+        // length, which truncated longer HTTP responses (the #96 failure mode).
+        // Still return the RESOLVED path so callers/model narrate only disk truth.
+        let dest: String = resolve_in_root(path, root)
+        let write_ok: Int = fs_write(dest, content)
+        if write_ok == 0 {
+            return json_safe("{\"error\":\"write failed - nothing landed at " + dest + "\"}")
+        }
+        return json_safe("{\"ok\":true,\"path\":\"" + dest + "\"}")
     }
     if str_eq(tool_name, "web_get") {
         let url: String = json_get(tool_input, "url")
@@ -1784,8 +1797,22 @@ fn dispatch_tool(tool_name: String, tool_input: String) -> String {
         if str_eq(content, "") {
             return json_safe("{\"error\":\"file not found\"}")
         }
+        // BUG-29 (Receipt Contract rule 1): when old_text was absent (or empty),
+        // str_replace was a silent no-op and the handler still claimed ok:true —
+        // a false receipt. Verify the text is actually present before replacing.
+        if str_eq(old_text, "") {
+            return json_safe("{\"error\":\"old_text is required\"}")
+        }
+        if !str_contains(content, old_text) {
+            return json_safe("{\"error\":\"old_text not found in file\"}")
+        }
         let updated: String = str_replace(content, old_text, new_text)
-        fs_write(resolved, updated)
+        // BUG-29: the fs_write result was also unchecked — a failed write still
+        // returned ok:true. Same honest-write check as write_file above.
+        let write_ok: Int = fs_write(resolved, updated)
+        if write_ok == 0 {
+            return json_safe("{\"error\":\"write failed\"}")
+        }
         return json_safe("{\"ok\":true}")
     }
     if str_eq(tool_name, "remember") {
@@ -1961,8 +1988,24 @@ fn handle_chat_agentic(body: String) -> String {
     // no root (or cleared the field), and we must not overwrite a server-configured root
     // from NEURON_AGENT_ROOT with an empty string, which would silently un-scope the agent.
     let ws_root: String = json_get(body, "agent_workspace_root")
+    // BUG-LEAK fix (2026-07-16): the root used to live ONLY in the shared key, so any
+    // request that omitted it INHERITED the previous session's folder (proven: a rootless
+    // curl session wrote into another session's run folder). Now each session keeps its
+    // own copy, and every request RE-ASSERTS its own root (possibly empty) into the shared
+    // key the tool guards read — no session can ever act under another session's root.
+    // Empty state still falls through to env NEURON_AGENT_ROOT inside
+    // agent_workspace_root(), so a server-configured root survives unchanged.
+    // LIMITATION (for review): assumes serialized request handling; true per-call scoping
+    // means threading session_id through dispatch_tool/classify — deeper change, Will's call.
+    let sess_for_root: String = json_get(body, "session_id")
     if !str_eq(ws_root, "") {
+        if !str_eq(sess_for_root, "") {
+            state_set("agent_workspace_root_" + sess_for_root, ws_root)
+        }
         state_set("agent_workspace_root", ws_root)
+    } else {
+        let own_root: String = if str_eq(sess_for_root, "") { "" } else { state_get("agent_workspace_root_" + sess_for_root) }
+        state_set("agent_workspace_root", own_root)
     }
 
     // L1 safety screen — agentic path must pass the same gate as layered_cycle.
@@ -2092,6 +2135,14 @@ fn handle_chat_agentic(body: String) -> String {
 
     // Use caller-supplied session_id if provided, otherwise generate a bridge id.
     let session_id: String = if str_eq(req_session, "") { next_bridge_id() } else { req_session }
+    // PAUSE-CONTRACT fix (2026-07-16): honor the client's require_approval field — the
+    // Phase 1c contract ("the soul pauses on EVERY tool; the client's tier gate decides
+    // what actually prompts") was never implemented engine-side, which made the client's
+    // Ask autonomy silently inert for builtin sub-escalate tools. Persisted per session
+    // (set/reset on every request) so the /approve resume path keeps the same behavior
+    // for the rest of the run. Absent/false = behavior identical to before this fix.
+    let req_ask_all: String = json_get(body, "require_approval")
+    state_set("require_approval_" + session_id, if str_eq(req_ask_all, "true") { "true" } else { "" })
     // Provider fork: OpenAI-compatible providers (Ollama/OpenAI/Grok/Gemini) take the plain-completion
     // path (v1, no tools); everything else stays on the Anthropic agentic loop (the default).
     let use_openai: Bool = !str_eq(llm_base_url(), "") && str_eq(llm_wire_format(), "openai")
@@ -2160,6 +2211,12 @@ fn handle_chat_agentic(body: String) -> String {
 fn agentic_loop(session_id: String, model: String, safe_sys: String, tools_json: String, messages_in: String, h: Map, tools_log_in: String) -> String {
     let api_url: String = "https://api.anthropic.com/v1/messages"
 
+    // PAUSE-CONTRACT fix (2026-07-16): when the client asked to approve every action
+    // (require_approval on the request, persisted per session), EVERY tool turn bridges —
+    // the client's tier gate decides what actually prompts vs auto-continues. Read from
+    // session state so the /approve resume re-entry keeps the same behavior mid-run.
+    let ask_all: Bool = !str_eq(session_id, "") && str_eq(state_get("require_approval_" + session_id), "true")
+
     let messages: String = messages_in
     let final_text: String = ""
     let tools_log: String = tools_log_in
@@ -2246,7 +2303,10 @@ fn agentic_loop(session_id: String, model: String, safe_sys: String, tools_json:
         // confirm). Escalated calls suspend to the client's consent flow; the
         // /approve round-trip is the only path that executes them.
         let risk_tier: String = if is_tool_turn { classify_tool_risk(tool_name, tool_input) } else { "" }
-        let needs_bridge: Bool = is_tool_turn && (str_eq(risk_tier, "escalate") || (!is_builtin_tool(tool_name) && !is_always_allowed))
+        // PAUSE-CONTRACT fix (2026-07-16): ask_all bridges EVERYTHING — stricter only.
+        // Escalate keeps its unconditional bridge; "always allow" shortcuts never apply
+        // under ask_all (the client owns its own standing grants at its tier gate).
+        let needs_bridge: Bool = is_tool_turn && (ask_all || str_eq(risk_tier, "escalate") || (!is_builtin_tool(tool_name) && !is_always_allowed))
 
         // Built-in tools dispatch locally; bridged tools yield "" (never sent upstream).
         let tool_result_raw: String = if is_tool_turn && !needs_bridge { dispatch_tool(tool_name, tool_input) } else { "" }
@@ -2386,6 +2446,10 @@ fn agentic_resume(session_id: String, tool_use_id: String, content: String) -> S
     if str_eq(blob, "") {
         return "{\"error\":\"unknown session_id\",\"reply\":\"\"}"
     }
+    // BUG-LEAK fix (2026-07-16): re-assert THIS session's own workspace root before the
+    // loop continues — a resume must never run under whatever root the last unrelated
+    // request happened to leave in the shared key.
+    state_set("agent_workspace_root", state_get("agent_workspace_root_" + session_id))
 
     let model: String = json_get(blob, "model")
     let safe_sys: String = json_get(blob, "safe_sys")

dist/neuron-api.c

@@ -10,7 +10,6 @@ el_val_t mem_remember(el_val_t content, el_val_t tags);
 el_val_t mem_recall(el_val_t query, el_val_t depth);
 el_val_t mem_search(el_val_t query, el_val_t limit);
 el_val_t mem_strengthen(el_val_t node_id);
-el_val_t mem_tombstone(el_val_t node_id);
 el_val_t mem_forget(el_val_t node_id);
 el_val_t mem_consolidate(void);
 el_val_t mem_save(el_val_t path);
@@ -361,7 +360,7 @@ el_val_t handle_api_remember(el_val_t body) {
   el_val_t sal = ({ el_val_t _if_result_14 = 0; if (str_eq(sal_str, EL_STR("0.95"))) { _if_result_14 = (el_from_float(0.95)); } else { _if_result_14 = (({ el_val_t _if_result_15 = 0; if (str_eq(sal_str, EL_STR("0.75"))) { _if_result_15 = (el_from_float(0.75)); } else { _if_result_15 = (({ el_val_t _if_result_16 = 0; if (str_eq(sal_str, EL_STR("0.25"))) { _if_result_16 = (el_from_float(0.25)); } else { _if_result_16 = (el_from_float(0.5)); } _if_result_16; })); } _if_result_15; })); } _if_result_14; });
   el_val_t base_tags = ({ el_val_t _if_result_17 = 0; if (str_eq(tags_raw, EL_STR(""))) { _if_result_17 = (EL_STR("[\"Memory\"]")); } else { _if_result_17 = (tags_raw); } _if_result_17; });
   el_val_t final_tags = ({ el_val_t _if_result_18 = 0; if (str_eq(project, EL_STR(""))) { _if_result_18 = (base_tags); } else { el_val_t inner = str_slice(base_tags, 1, (str_len(base_tags) - 1)); _if_result_18 = (el_str_concat(el_str_concat(el_str_concat(el_str_concat(EL_STR("["), inner), EL_STR(",\"project:")), project), EL_STR("\"]"))); } _if_result_18; });
-  el_val_t id = engram_node_full(content, EL_STR("Memory"), EL_STR("memory:remembered"), sal, sal, el_from_float(0.9), EL_STR("Episodic"), final_tags);
+  el_val_t id = engram_node_full(content, EL_STR("Memory"), EL_STR("memory:remembered"), el_from_float(sal), el_from_float(sal), el_from_float(0.9), EL_STR("Episodic"), final_tags);
   if (!api_persisted(id)) {
     return api_not_persisted(id);
   }
@@ -384,7 +383,7 @@ el_val_t handle_api_node_create(el_val_t body) {
   el_val_t tags = ({ el_val_t _if_result_22 = 0; if (str_eq(tags_raw, EL_STR(""))) { _if_result_22 = (el_str_concat(el_str_concat(EL_STR("[\""), node_type), EL_STR("\"]"))); } else { _if_result_22 = (tags_raw); } _if_result_22; });
   el_val_t importance = json_get(body, EL_STR("importance"));
   el_val_t sal = ({ el_val_t _if_result_23 = 0; if (str_eq(importance, EL_STR("critical"))) { _if_result_23 = (el_from_float(0.95)); } else { _if_result_23 = (({ el_val_t _if_result_24 = 0; if (str_eq(importance, EL_STR("high"))) { _if_result_24 = (el_from_float(0.75)); } else { _if_result_24 = (({ el_val_t _if_result_25 = 0; if (str_eq(importance, EL_STR("low"))) { _if_result_25 = (el_from_float(0.25)); } else { _if_result_25 = (el_from_float(0.5)); } _if_result_25; })); } _if_result_24; })); } _if_result_23; });
-  el_val_t id = engram_node_full(content, node_type, label, sal, sal, el_from_float(0.9), tier, tags);
+  el_val_t id = engram_node_full(content, node_type, label, el_from_float(sal), el_from_float(sal), el_from_float(0.9), tier, tags);
   if (!api_persisted(id)) {
     return api_not_persisted(id);
   }
@@ -497,9 +496,8 @@ el_val_t handle_api_capture_knowledge(el_val_t body) {
     return api_err(EL_STR("content is required"));
   }
   el_val_t full = ({ el_val_t _if_result_44 = 0; if (str_eq(title, EL_STR(""))) { _if_result_44 = (content); } else { _if_result_44 = (el_str_concat(el_str_concat(title, EL_STR(": ")), content)); } _if_result_44; });
-  el_val_t lbl = str_slice(title, 0, 80);
   el_val_t tags = EL_STR("[\"Knowledge\",\"captured\"]");
-  el_val_t id = engram_node_full(full, EL_STR("Knowledge"), lbl, el_from_float(0.85), el_from_float(0.8), el_from_float(0.9), EL_STR("Episodic"), tags);
+  el_val_t id = engram_node_full(full, EL_STR("Knowledge"), EL_STR("knowledge:captured"), el_from_float(0.85), el_from_float(0.8), el_from_float(0.9), EL_STR("Episodic"), tags);
   if (!api_persisted(id)) {
     return api_not_persisted(id);
   }
@@ -517,7 +515,7 @@ el_val_t handle_api_evolve_knowledge(el_val_t body) {
     return api_err_protected(prior_id);
   }
   el_val_t tags = EL_STR("[\"Knowledge\",\"evolved\"]");
-  el_val_t new_id = engram_node_full(content, EL_STR("Knowledge"), EL_STR(""), el_from_float(0.75), el_from_float(0.75), el_from_float(0.9), EL_STR("Episodic"), tags);
+  el_val_t new_id = engram_node_full(content, EL_STR("Knowledge"), EL_STR("knowledge:evolved"), el_from_float(0.75), el_from_float(0.75), el_from_float(0.9), EL_STR("Episodic"), tags);
   if (!api_persisted(new_id)) {
     return api_not_persisted(new_id);
   }
@@ -539,7 +537,7 @@ el_val_t handle_api_promote_knowledge(el_val_t body) {
   }
   el_val_t tags_raw = json_get(body, EL_STR("tags"));
   el_val_t tags = ({ el_val_t _if_result_45 = 0; if (str_eq(tags_raw, EL_STR(""))) { _if_result_45 = (EL_STR("[\"Knowledge\",\"tier:canonical\",\"disposition:stable\"]")); } else { _if_result_45 = (tags_raw); } _if_result_45; });
-  el_val_t new_id = engram_node_full(content, EL_STR("Knowledge"), EL_STR(""), el_from_float(0.9), el_from_float(0.9), el_from_float(1.0), EL_STR("Canonical"), tags);
+  el_val_t new_id = engram_node_full(content, EL_STR("Knowledge"), EL_STR("knowledge:canonical"), el_from_float(0.9), el_from_float(0.9), el_from_float(1.0), EL_STR("Canonical"), tags);
   if (!api_persisted(new_id)) {
     return api_not_persisted(new_id);
   }
@@ -710,7 +708,7 @@ el_val_t handle_api_evolve_memory(el_val_t body) {
   el_val_t sal_str = ({ el_val_t _if_result_65 = 0; if (str_eq(importance, EL_STR("critical"))) { _if_result_65 = (EL_STR("0.95")); } else { _if_result_65 = (({ el_val_t _if_result_66 = 0; if (str_eq(importance, EL_STR("high"))) { _if_result_66 = (EL_STR("0.75")); } else { _if_result_66 = (({ el_val_t _if_result_67 = 0; if (str_eq(importance, EL_STR("low"))) { _if_result_67 = (EL_STR("0.25")); } else { _if_result_67 = (EL_STR("0.50")); } _if_result_67; })); } _if_result_66; })); } _if_result_65; });
   el_val_t sal = ({ el_val_t _if_result_68 = 0; if (str_eq(sal_str, EL_STR("0.95"))) { _if_result_68 = (el_from_float(0.95)); } else { _if_result_68 = (({ el_val_t _if_result_69 = 0; if (str_eq(sal_str, EL_STR("0.75"))) { _if_result_69 = (el_from_float(0.75)); } else { _if_result_69 = (({ el_val_t _if_result_70 = 0; if (str_eq(sal_str, EL_STR("0.25"))) { _if_result_70 = (el_from_float(0.25)); } else { _if_result_70 = (el_from_float(0.5)); } _if_result_70; })); } _if_result_69; })); } _if_result_68; });
   el_val_t tags = EL_STR("[\"Memory\",\"evolved\"]");
-  el_val_t new_id = engram_node_full(content, EL_STR("Memory"), EL_STR("memory:evolved"), sal, sal, el_from_float(0.9), EL_STR("Episodic"), tags);
+  el_val_t new_id = engram_node_full(content, EL_STR("Memory"), EL_STR("memory:evolved"), el_from_float(sal), el_from_float(sal), el_from_float(0.9), EL_STR("Episodic"), tags);
   if (!str_eq(prior_id, EL_STR("")) && !str_eq(new_id, EL_STR(""))) {
     engram_connect(new_id, prior_id, el_from_float(0.9), EL_STR("supersedes"));
   }
@@ -785,7 +783,7 @@ el_val_t handle_api_cultivate(el_val_t body) {
     el_val_t importance = json_get(body, EL_STR("importance"));
     el_val_t sal = ({ el_val_t _if_result_71 = 0; if (str_eq(importance, EL_STR("critical"))) { _if_result_71 = (el_from_float(0.95)); } else { _if_result_71 = (({ el_val_t _if_result_72 = 0; if (str_eq(importance, EL_STR("high"))) { _if_result_72 = (el_from_float(0.75)); } else { _if_result_72 = (({ el_val_t _if_result_73 = 0; if (str_eq(importance, EL_STR("low"))) { _if_result_73 = (el_from_float(0.25)); } else { _if_result_73 = (el_from_float(0.5)); } _if_result_73; })); } _if_result_72; })); } _if_result_71; });
     el_val_t tags = EL_STR("[\"Memory\",\"evolved\",\"cultivated\"]");
-    el_val_t new_id = engram_node_full(content, EL_STR("Memory"), EL_STR("memory:cultivated"), sal, sal, el_from_float(0.9), EL_STR("Episodic"), tags);
+    el_val_t new_id = engram_node_full(content, EL_STR("Memory"), EL_STR("memory:cultivated"), el_from_float(sal), el_from_float(sal), el_from_float(0.9), EL_STR("Episodic"), tags);
     if (!str_eq(prior_id, EL_STR("")) && !str_eq(new_id, EL_STR(""))) {
       engram_connect(new_id, prior_id, el_from_float(0.9), EL_STR("supersedes"));
     }
@@ -828,8 +826,8 @@ el_val_t handle_api_consolidate(el_val_t body) {
   el_val_t summary = json_get(body, EL_STR("summary"));
   el_val_t snap = state_get(EL_STR("soul_snapshot_path"));
   if (!str_eq(snap, EL_STR(""))) {
-    el_val_t saved = engram_save(snap);
-    if (saved == 0) {
+    el_val_t save_result = engram_save(snap);
+    if (str_eq(save_result, EL_STR(""))) {
       println(el_str_concat(el_str_concat(EL_STR("[api] consolidate: engram_save failed for "), snap), EL_STR(" \xe2\x80\x94 snapshot may be out of sync")));
     }
   }

dist/neuron.c

@@ -541,7 +541,7 @@ int main(int _argc, char** _argv) {
   axon_raw = env(EL_STR("NEURON_API_URL"));
   axon_base = ({ el_val_t _if_result_47 = 0; if (str_eq(axon_raw, EL_STR(""))) { _if_result_47 = (EL_STR("http://localhost:7771")); } else { _if_result_47 = (axon_raw); } _if_result_47; });
   studio_dir_raw = env(EL_STR("SOUL_STUDIO_DIR"));
-  studio_dir = ({ el_val_t _if_result_48 = 0; if (str_eq(studio_dir_raw, EL_STR(""))) { _if_result_48 = (EL_STR("/Users/will/Development/neuron-technologies/products/cgi-studio/el-daemon")); } else { _if_result_48 = (studio_dir_raw); } _if_result_48; });
+  studio_dir = ({ el_val_t _if_result_48 = 0; if (str_eq(studio_dir_raw, EL_STR(""))) { _if_result_48 = (el_str_concat(env(EL_STR("HOME")), EL_STR("/Development/neuron-technologies/products/cgi-studio/el-daemon"))); } else { _if_result_48 = (studio_dir_raw); } _if_result_48; });
   println(el_str_concat(el_str_concat(el_str_concat(EL_STR("[soul] boot - cgi="), soul_cgi_id), EL_STR(" port=")), int_to_str(port)));
   using_http_engram = !str_eq(engram_url_raw, EL_STR(""));
   engram_load(snapshot);

dist/soul-with-nlg.el

@@ -21304,7 +21304,7 @@ println("[memory] consolidate stats=" + stats)
 let soul_axon_base_raw: String = env("NEURON_API_URL")
 let soul_axon_base: String = if str_eq(soul_axon_base_raw, "") { "http://localhost:7771" } else { soul_axon_base_raw }
 let soul_token: String = env("NEURON_TOKEN")
-let soul_studio_ui_dir: String = "/Users/will/Development/neuron-technologies/products/cgi-studio/el-daemon"
+let soul_studio_ui_dir: String = env("HOME") + "/Development/neuron-technologies/products/cgi-studio/el-daemon"
 
 // ── Runtime bridge helpers ────────────────────────────────────────────────────
 

docs/NARRATED-RUNS-ENGINE-NOTES-20260713.md

@@ -0,0 +1,34 @@
+# Narrated runs — engine notes for Will (2026-07-13)
+
+Source half: commit aa67f86 on feat/agent-phase1-soul (run-progress ledger,
+`/api/run-progress/<sid>` route, narration on the pause envelope, config display
+default). E2E-verified via the compiled test bed on Tim's clean profile.
+
+Compiled-form-only fixes (in `neuron-container-build/soul-narrated-runs-20260713.patch`,
+applies ON TOP of `soul-webfix-20260711.patch` — these need porting to chat.el when the
+webfix itself is ported):
+
+1. **pause_turn + tool_use interleave**: a pause_turn response can ALSO carry a client
+   tool_use; resuming verbatim leaves it unpaired → Anthropic 400 "tool_use ids were
+   found without tool_result". Fix: tool-bearing pause rounds are tool turns
+   (dispatch + pair); verbatim resume only when the round has no client tool.
+2. **Agentic toolset scope**: agentic_tools_all() fed EVERY connector/MCP tool (Notion,
+   code-execution…) into the loop. Code-execution flips the API into programmatic
+   tool calling, whose pairing protocol the single-tool manual loop does not speak —
+   source of the dangling-pair 400s AND the bash_code_execution workspace-dodge.
+   Fix: handle_chat_agentic declares builtins + ONE server web_search only.
+   Connector tools return when the loop gains real multi-tool/programmatic support.
+3. **disable_parallel_tool_use: true** on agentic requests — the loop captures only the
+   first tool_use per round; Opus-class models parallel-call. Enforce the invariant.
+4. **web_search server-tool default variant → web_search_20250305 (GA)**. The 20260209
+   variant couples to code-execution ⇒ programmatic mode (see #2, and the June note:
+   "inert unless code-execution attached").
+5. **Homegrown web_search removed** from the tool catalog (server-side is the one tool).
+
+Known engine debts this work surfaced (not fixed):
+
+- **Poisoned session history**: a failed run persists the malformed assistant turn; every
+  later turn in that session replays it and 400s. Needs history sanitation on load.
+- **Huge-history invalid-escape 400** (~346KB request) — likely the same poisoned blob.
+- **macOS note**: replacing a binary in place invalidates its ad-hoc signature (instant
+  silent SIGKILL, looks like exit 0). `rm + cp + codesign -f -s -` is the swap ritual.

mcp-wrapper/src/main.el

@@ -311,8 +311,25 @@ fn delete_by_id(args: String) -> String {
     if str_eq(id, "") {
         return mcp_text_result("error: id is required")
     }
-    // Soul does not yet expose a delete HTTP route; acknowledge the request
-    return mcp_json_result("{\"ok\":true,\"deleted\":\"" + id + "\",\"note\":\"soft-deleted\"}")
+    // BUG-18 (Receipt Contract rule 1): this handler used to FABRICATE
+    // {"ok":true,...,"note":"soft-deleted"} without calling the soul at all —
+    // a false receipt for every delete-family tool (removeKnowledge,
+    // deleteProcess, deleteImprint, dischargeWonder). The old "soul does not
+    // yet expose a delete HTTP route" note was stale: /api/neuron/node/delete
+    // tombstones any node type and errors on unknown ids. Route there and
+    // propagate the soul's real answer.
+    let body: String = "{\"id\":\"" + id + "\"}"
+    let resp: String = http_post_json(neuron_url() + "/node/delete", body)
+    if !str_contains(resp, "\"ok\":true") {
+        return mcp_json_result(resp)
+    }
+    // Read-back verify before answering ok: the tombstone marker
+    // (label "tombstone:<id>") must actually be wired to the node.
+    let check: String = http_get(neuron_url() + "/graph?id=" + id + "&depth=1")
+    if !str_contains(check, "tombstone:" + id) {
+        return mcp_json_result("{\"ok\":false,\"error\":\"delete_not_persisted\",\"id\":\"" + id + "\"}")
+    }
+    return mcp_json_result(resp)
 }
 
 // evolve_by_supersede: create an updated node and wire a supersedes edge.
@@ -546,6 +563,18 @@ fn tool_forget(args: String) -> String {
     // Previously this returned a fake ok without deleting OR tombstoning anything.
     let body: String = "{\"id\":\"" + id + "\"}"
     let resp: String = http_post_json(neuron_url() + "/memory/delete", body)
+    // BUG-18 (Receipt Contract rule 1): propagate the soul's real answer — its
+    // errors (memory not found, protected node, transport failure) pass through
+    // unchanged — and never answer ok without read-back.
+    if !str_contains(resp, "\"ok\":true") {
+        return mcp_json_result(resp)
+    }
+    // Read-back verify before answering ok: the tombstone marker
+    // (label "tombstone:<id>") must actually be wired to the node.
+    let check: String = http_get(neuron_url() + "/graph?id=" + id + "&depth=1")
+    if !str_contains(check, "tombstone:" + id) {
+        return mcp_json_result("{\"ok\":false,\"error\":\"delete_not_persisted\",\"id\":\"" + id + "\"}")
+    }
     return mcp_json_result(resp)
 }
 

neuron-api.el

@@ -59,8 +59,14 @@ fn api_query_param(path: String, key: String) -> String {
     if pos < 0 { return "" }
     let after: String = str_slice(qs, pos + str_len(needle), str_len(qs))
     let amp: Int = str_index_of(after, "&")
-    if amp < 0 { return after }
-    return str_slice(after, 0, amp)
+    let raw: String = if amp < 0 { after } else { str_slice(after, 0, amp) }
+    // URL-decode the extracted value BEFORE any downstream tokenizing. Clients
+    // percent-encode spaces (%20) and form-encode them as '+', so a multi-word
+    // query like "foo bar" arrives as "foo%20bar" / "foo+bar". Left undecoded,
+    // the ranked lexical search sees a single un-splittable token and matches
+    // nothing (single-word queries still hit). url_decode maps '+' -> space
+    // and %XX -> byte, restoring the word boundaries for recall + knowledge search.
+    return url_decode(raw)
 }
 
 fn api_query_int(path: String, key: String, default_val: Int) -> Int {
@@ -271,22 +277,18 @@ fn memory_hide_tombstoned(raw: String, path: String) -> String {
 // Spread-activates from session intent, loads self-root neighbors,
 // surfaces recent InternalStateEvent nodes, returns stats + recent nodes.
 fn handle_api_begin_session(body: String) -> String {
-    // PAYLOAD BOUND (2026-07-30 self-review): this handler was the only
-    // working-set endpoint that concatenated UNBOUNDED engram queries —
+    // PAYLOAD BOUND: this handler was the highest-fanout working-set endpoint —
     // a depth-2 spread PLUS the full neighbor dump of the self-identity hub
-    // (highest-fanout node in the graph, ~80KB alone; node JSON carries full
-    // content + embeddings). On the ~12k-node store the assembled response
-    // ran to multiple MB, then roughly doubled through two rounds of JSON
-    // re-escaping in the MCP wrapper — the client saw "socket connection
-    // closed unexpectedly" on every beginSession call. Fix: depth-2 → depth-1
-    // spread, and drop the self-hub dump entirely (identity loading has its
-    // own dedicated tool, inspectGraph; duplicating it here served nothing).
-    // self_neighbors key retained as [] for response-shape compatibility.
+    // (~90KB alone; node JSON carries full content + embeddings). On the ~12k-node
+    // store the assembled response ran to ~900KB, then roughly doubled through two
+    // rounds of JSON re-escaping in the MCP wrapper — the client saw "socket
+    // connection closed unexpectedly" on every beginSession call. Fix: depth-2 →
+    // depth-1 spread, drop the self-hub dump (identity loading has its own tool,
+    // inspectGraph), cap every list, and project each node to a light identity +
+    // a bounded, UTF-8-safe content snippet. self_neighbors kept as [] for
+    // response-shape compatibility. Response drops ~900KB → ~12KB; full content
+    // stays available on demand via recall / fetch / inspectGraph.
     let stats: String = engram_stats_json()
-    // PAYLOAD BOUND (2026-07-31): compact every list to a digest. The raw
-    // activate/scan builtins emit FULL node objects (content up to ~90KB each);
-    // unbounded concatenation reached ~900KB and closed the MCP client socket.
-    // Cap counts + project to identity + UTF-8-safe content snippets → <~150KB.
     let activated_raw: String = engram_activate_json("session start recent memory important", 1)
     let activated: String = api_compact_activated(activated_raw, 8, 240)
     let state_events_raw: String = engram_scan_nodes_by_type_json("InternalStateEvent", 5, 0)
@@ -304,9 +306,9 @@ fn handle_api_begin_session(body: String) -> String {
 // Spread-activates from "active work" intent + recent nodes.
 fn handle_api_compile_ctx(body: String) -> String {
     let stats: String = engram_stats_json()
-    // PAYLOAD BOUND (2026-07-31): same digest treatment as begin_session. This
-    // handler's depth-2 spread returns even more full nodes, so bounding here is
-    // essential — cap to 10 activated + 20 recent, project to snippets.
+    // PAYLOAD BOUND: same digest treatment as begin_session. This handler's
+    // depth-2 spread returns even more full nodes, so bounding here is essential —
+    // cap to 10 activated + 20 recent, project to UTF-8-safe snippets.
     let activated_raw: String = engram_activate_json("active work context current task in progress", 2)
     let activated: String = api_compact_activated(activated_raw, 10, 240)
     let recent_raw: String = engram_scan_nodes_json(20, 0)

neuron-dev-setup/README.md

@@ -0,0 +1,171 @@
+# neuron-dev-setup — one-command Neuron CORE dev stack
+
+Stand up an identical **Neuron brain + agent** on a fresh Mac so any developer
+gets the same local runtime to build against. This is the **CORE** dev stack
+only — the four native `launchd` services that make Neuron think, remember, and
+speak MCP to Claude Code. Will's personal automations (catalyst, telegram,
+vessels, studio, self-review, world-integrator, council, compressor, snapshots,
+act-runner, …) are **deliberately excluded**.
+
+```
+  ┌─────────────┐        ┌──────────────┐
+  │  soul :7770 │ ─────► │ engram :8742 │     the mind ──► its memory substrate
+  └─────────────┘        └──────────────┘
+        ▲
+        │
+  ┌───────────────────┐
+  │ mcp-wrapper :17779│  ─── MCP surface over the soul HTTP API (internal)
+  └───────────────────┘
+        ▲
+        │
+  ┌────────────────┐
+  │ mcp-proxy :7779│  ◄─── Claude Code connects here (stable front door)
+  └────────────────┘
+```
+
+Claude Code's `neuron` MCP server points at `http://127.0.0.1:7779/` — the proxy.
+The proxy forwards to the wrapper (`:17779`), which calls the soul (`:7770`),
+which reads/writes the engram (`:8742`). The engram is the persistent brain.
+
+## Quick start
+
+```bash
+git clone <this-repo> && cd neuron-dev-setup
+cp config.env.example config.env      # optional — edit ports/paths if you like
+./install.sh                          # prompts for your Anthropic API key
+```
+
+Then verify:
+
+```bash
+curl http://localhost:8742/health     # engram
+curl http://localhost:7770/health         # soul
+curl http://localhost:7779/health         # mcp-proxy (what Claude Code uses)
+launchctl list | grep ai.neuron
+```
+
+Open Claude Code — the `neuron` MCP tools should be live, backed by **your own**
+local brain. `./install.sh --dry-run` shows every action without touching anything.
+
+## What the installer does (8 phases)
+
+| Phase | Action |
+|------|--------|
+| 1 | Preflight: macOS/arm64, ensure `git cc curl python3` + `openssl@3` (via Homebrew) |
+| 2 | Prompt for the **Anthropic API key**, store it in the **macOS Keychain** (never a file) |
+| 3 | Clone `neuron`, `engram`, `foundation`; fetch the El toolchain; build 4 binaries + `forge` |
+| 4 | Lay down `~/.neuron/{bin,logs,engram}` and the templated `soul-wrapper.sh` |
+| 5 | Generate + load the 4 core LaunchAgents (engram → soul → wrapper → proxy) |
+| 6 | Seed a fresh engram with the **genesis identity** via `forge install` |
+| 7 | Install Claude config: `neuron` agent, core hooks, local MCP registration |
+| 8 | Health-check all four ports |
+
+Everything is **idempotent** (safe to re-run) and **templated** to the invoking
+user's `$HOME` — no path is hardcoded to another machine.
+
+## Prerequisites
+
+- macOS on Apple Silicon (uses `launchd`; soul build flags assume arm64).
+- **Xcode Command Line Tools** (`xcode-select --install`) — provides `cc`, `git`.
+- **Homebrew** — for `openssl@3`, `curl`.
+- An **Anthropic API key** — the soul's inference provider. Prompted for; stored
+  in Keychain under service `neuron-llm-0-key`; read at launch by `soul-wrapper.sh`.
+- **Git access** to Gitea (`git.neuralplatform.ai`) for the source repos.
+- **GCP access** to project `neuron-785695` Artifact Registry (default El
+  toolchain source). Ask Will to grant it, or set `EL_TOOLCHAIN_SOURCE=local`.
+
+## Core-stack map (what gets replicated)
+
+| Service | Port | Binary | Built from | LaunchAgent |
+|---------|------|--------|------------|-------------|
+| soul | 7770 | `neuron/dist/neuron` | `dist/soul.c` + El runtime, `cc` (CI recipe) | `ai.neuron.soul` |
+| engram | 8742 | `engram/dist/engram` | `engram` repo `src/server.el` via `elc`→`cc` | `ai.neuron.engram` |
+| mcp-wrapper | 17779 | `neuron/mcp-wrapper/dist/neuron-mcp-wrapper` | `mcp-wrapper/src/main.el` | `ai.neuron.mcp-wrapper` |
+| mcp-proxy | 7779 | `neuron/mcp-proxy/dist/neuron-mcp-proxy` | `mcp-proxy/src/main.el` | `ai.neuron.mcp-proxy` |
+
+**`~/.neuron` layout the installer creates**
+
+```
+~/.neuron/
+  bin/soul-wrapper.sh     # reads Anthropic key from Keychain, execs the soul binary
+  logs/                   # soul.*.log, engram.log, mcp-*.log
+  engram/                 # ENGRAM_DATA_DIR — the persistent brain (snapshot.json + db)
+```
+
+**Identity seed.** `foundation/forge/seeds/neuron-genesis-seed.json` carries
+`identity_nodes[]` + `edges[]` with **fixed** knowledge-node IDs (e.g.
+`kn-efeb4a5b-5aff-4759-8a97-7233099be6ee`, the "self" traversal root). Those exact
+IDs are referenced by the SessionStart self-load hook and the neuron agent, so
+seeding must **preserve IDs** — `forge install <seed>` is the mechanism.
+
+**Claude config installed** (`~/.claude/`)
+
+- `agents/neuron.md` — the Neuron agent (identity, session protocol, five primitives).
+- `mcp.json` — registers `neuron` → `http://127.0.0.1:7779/`.
+- `settings.json` hooks (CORE subset only):
+  - `SessionStart` → `neuron-self-load.sh` (loads identity from the seeded engram)
+  - `PreToolUse:Agent` → `neuron-agent-preamble.sh` (subagents load substrate first)
+  - `PreCompact` → `pre-compact.sh` (clean context recovery)
+
+### Deliberately EXCLUDED from core
+
+- **`check-active-contexts.sh`** and **`require-execution-context.sh`** — these
+  depend on a separate filesystem repo `~/Development/projects/active/neuron/synapse`.
+  `require-execution-context.sh` is a hard `Edit/Write` gate that would **block a
+  fresh dev from editing any file** without that synapse repo. Not core; excluded.
+- `engram-mirror.py` (PostToolUse) — optional; mirrors MCP writes to engram.
+- All Will-personal LaunchAgents: `catalyst-*`, `telegram-gateway`, `vessel.*`,
+  `studio`, `self-review`, `world-integrator`, `council`, `compressor`,
+  `cultivation-digest`, `snapshot-backup`, `engram-backup`, `act-runner`, `keymap`,
+  `invest`, and the disabled `ai.neuron.api` (`:7771` is a personal Python
+  perception helper — confirmed not core).
+
+## Secrets — how they're handled
+
+- **Anthropic key**: prompted for; stored in Keychain; read at launch. Never in a
+  plist, this repo, or a log.
+- **Engram local token** (`ENGRAM_API_KEY`): a *loopback-only* dev token, not a
+  cloud secret. Defaults to a generated `ntn-dev-*` value; override in `config.env`.
+- No cloud tokens, Vault tokens, CF-Access secrets, or founder keys are copied.
+  (Will's live `start-daemon.sh`/`neuron-api-launch.sh` contain such keys — this
+  installer intentionally does **not** use those files.)
+
+## Uninstall
+
+```bash
+./uninstall.sh                # stop + remove the 4 LaunchAgents and added Claude hooks
+./uninstall.sh --purge-data   # ALSO delete ~/.neuron/engram (destroys the brain)
+```
+
+## OPEN QUESTIONS (need Will to confirm)
+
+1. **El toolchain acquisition.** The default path fetches `el-runtime-c/-h` and
+   `el-elc` from GCP Artifact Registry (mirrors `neuron/.gitea/workflows/ci.yaml`).
+   A new dev needs GCP access to `neuron-785695`. Is that the intended path, or
+   should the El SDK be published/vendored for onboarding?
+2. **`elc` invocation for engram/wrapper/proxy.** The soul build (`cc dist/soul.c
+   + el_runtime.c`) is verified from CI. The `.el → .c` transpile step for engram,
+   mcp-wrapper, and mcp-proxy is inferred (`elc <src> -o <out.c>`). Confirm the
+   exact flags / entrypoints (CI notes `elb` OOMs on Linux; macOS builds differ).
+3. **`forge install` ID preservation.** Confirm `forge install` writes the seed's
+   fixed `kn-` IDs verbatim (the self-load hook hardcodes `kn-efeb4a5b…`). If it
+   re-mints IDs, the hook + agent identity load would break on a fresh brain.
+4. **engram repo layout.** The live engram binary is built from `src/server.el`
+   (Gitea repo `neuron-technologies/engram`, cloned in CI). Confirm that repo is
+   the canonical source for onboarding (the local `foundation/el/engram` copy has
+   the same `src/server.el`).
+5. **Home for this bundle** — see below.
+
+## Where this should live (recommendation)
+
+**Recommendation: a dedicated `neuron-dev-setup` (or `neuron-onboarding`) repo —
+NOT `neuron-code`.** `neuron-code` already exists as a real product ("Neuron Code",
+a coding tool with `nc-cli` + vessels — local `products/neuron-code` has commits);
+repurposing it for onboarding would collide with a shipped product's identity.
+
+This bundle was scaffolded as `neuron-dev-setup/` on branch `feat/neuron-dev-setup`
+in the **`neuron` repo** (off `origin/main`) and opened as a PR for review, because
+the neuron repo already hosts the soul source, the verified CI build recipe, and
+the mcp-wrapper/proxy sources — the natural review surface. If you'd rather it be
+its own repo, move this directory into a fresh `neuron-dev-setup` repo verbatim;
+nothing here depends on living inside the neuron repo.

neuron-dev-setup/config.env.example

@@ -0,0 +1,45 @@
+# neuron-dev-setup — configuration
+# Copy to  config.env  and edit if you want non-default paths/ports.
+# install.sh sources this file if it exists; otherwise it uses these defaults.
+# NOTHING here is a secret. The Anthropic API key is read from your Keychain,
+# never from this file. See README.md.
+
+# ── Where the core stack lives ────────────────────────────────────────────────
+# All paths are relative to your own $HOME — never hardcode another user's home.
+NEURON_HOME="${HOME}/.neuron"                       # runtime home: bin/, logs/, engram data
+DEV_ROOT="${HOME}/Development/neuron-technologies"   # where source repos are cloned/built
+
+# ── Git remotes (Gitea is primary) ───────────────────────────────────────────
+GITEA_BASE="git@git.neuralplatform.ai:neuron-technologies"
+NEURON_REPO_URL="${GITEA_BASE}/neuron.git"          # soul + mcp-wrapper + mcp-proxy source
+ENGRAM_REPO_URL="${GITEA_BASE}/engram.git"          # engram memory substrate
+# NOTE: there is no foundation.git repo. The El toolchain is fetched via
+# EL_TOOLCHAIN_SOURCE below; the forge seed installer is optional (Phase 6).
+NEURON_REPO_BRANCH="main"
+
+# ── Ports (must match across services; change only if a port clashes) ─────────
+SOUL_PORT="7770"        # soul daemon HTTP API
+ENGRAM_PORT="8742"      # engram memory substrate
+WRAPPER_PORT="17779"    # mcp-wrapper (internal, talks to soul)
+PROXY_PORT="7779"       # mcp-proxy (stable front door Claude Code connects to)
+
+# ── Engram ────────────────────────────────────────────────────────────────────
+ENGRAM_DATA_DIR="${NEURON_HOME}/engram"
+# Local shared auth token for the engram/soul HTTP APIs on loopback. This is a
+# LOCAL dev token (not a cloud secret); override it if you like. install.sh will
+# generate a random one if you leave it empty.
+ENGRAM_API_KEY="ntn-dev-local"
+
+# ── El toolchain source (needed to build engram / mcp-wrapper / mcp-proxy) ────
+# Option A (default): fetch prebuilt El runtime + elc from GCP Artifact Registry
+#   (requires `gcloud auth` with access to project neuron-785695 — ask Will).
+#   Without gcloud the installer skips the El-dependent builds and still completes.
+# Option B: use a prebuilt El toolchain (elc + el_runtime.{c,h}) you have already
+#   staged in ${DEV_ROOT}/.el-runtime.
+EL_TOOLCHAIN_SOURCE="artifact-registry"   # artifact-registry | local
+GCP_PROJECT="neuron-785695"
+GCP_AR_REPO="foundation-prod"
+GCP_AR_LOCATION="us-central1"
+
+# ── Keychain service name for the Anthropic key (read by soul-wrapper.sh) ─────
+KEYCHAIN_SERVICE="neuron-llm-0-key"

neuron-dev-setup/install.sh

@@ -0,0 +1,441 @@
+#!/usr/bin/env bash
+#
+# neuron-dev-setup / install.sh
+# ─────────────────────────────────────────────────────────────────────────────
+# One-command onboarding for the Neuron CORE dev stack on a fresh Mac.
+#
+# Stands up, as native launchd services, the four processes a developer needs to
+# have an identical "Neuron brain + agent" to build against:
+#
+#     soul  (:7770)  ──►  engram (:8742)        the mind + its memory substrate
+#       ▲                     ▲
+#       │                     │
+#   mcp-wrapper (:17779) ──►  soul              MCP surface over the soul API
+#       ▲
+#       │
+#   mcp-proxy   (:7779)  ◄── Claude Code        stable MCP front door
+#
+# It also seeds a fresh engram with Neuron's identity (the genesis seed) and lays
+# down the Claude Code config (neuron agent + core hooks + local MCP registration)
+# so a new dev's `claude` talks to *their own* local Neuron.
+#
+# DESIGN RULES
+#   * Idempotent: safe to re-run. Existing state is detected and reused.
+#   * Templated: every path/port/user is derived from $HOME and config.env.
+#     Nothing is hardcoded to another developer's machine.
+#   * Secret-free: the Anthropic key is prompted for and stored in the macOS
+#     Keychain. No key is ever written to a plist, this repo, or a logfile.
+#
+# USAGE
+#   ./install.sh                 # full install
+#   ./install.sh --dry-run       # print what would happen, touch nothing
+#   ./install.sh --skip-build    # assume binaries already built (see --use-local)
+#   ./install.sh --skip-services # lay down files but don't load LaunchAgents
+#   ./install.sh --help
+# ─────────────────────────────────────────────────────────────────────────────
+set -euo pipefail
+
+# ── Locate ourselves ─────────────────────────────────────────────────────────
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TEMPLATES="${SCRIPT_DIR}/templates"
+
+# ── Flags ────────────────────────────────────────────────────────────────────
+DRY_RUN=0; SKIP_BUILD=0; SKIP_SERVICES=0; USE_LOCAL_BINARIES=0
+for arg in "$@"; do
+  case "$arg" in
+    --dry-run)       DRY_RUN=1 ;;
+    --skip-build)    SKIP_BUILD=1 ;;
+    --skip-services) SKIP_SERVICES=1 ;;
+    --use-local)     USE_LOCAL_BINARIES=1 ;;
+    --help|-h)
+      sed -n '2,40p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+      exit 0 ;;
+    *) echo "unknown flag: $arg" >&2; exit 2 ;;
+  esac
+done
+
+# ── Pretty logging ───────────────────────────────────────────────────────────
+c_blue=$'\033[1;34m'; c_grn=$'\033[1;32m'; c_yel=$'\033[1;33m'; c_red=$'\033[1;31m'; c_off=$'\033[0m'
+step() { echo "${c_blue}▶${c_off} $*"; }
+ok()   { echo "${c_grn}✓${c_off} $*"; }
+warn() { echo "${c_yel}!${c_off} $*"; }
+die()  { echo "${c_red}✗ $*${c_off}" >&2; exit 1; }
+run()  { if [ "$DRY_RUN" = 1 ]; then echo "   [dry-run] $*"; else eval "$*"; fi; }
+
+# ── Load config ──────────────────────────────────────────────────────────────
+if [ -f "${SCRIPT_DIR}/config.env" ]; then
+  # shellcheck disable=SC1091
+  source "${SCRIPT_DIR}/config.env"
+else
+  # shellcheck disable=SC1091
+  source "${SCRIPT_DIR}/config.env.example"
+  warn "No config.env found — using defaults from config.env.example."
+fi
+
+# Derived / defaulted values (never hardcode a home directory)
+: "${NEURON_HOME:=${HOME}/.neuron}"
+: "${DEV_ROOT:=${HOME}/Development/neuron-technologies}"
+: "${SOUL_PORT:=7770}"; : "${ENGRAM_PORT:=8742}"; : "${WRAPPER_PORT:=17779}"; : "${PROXY_PORT:=7779}"
+: "${ENGRAM_DATA_DIR:=${NEURON_HOME}/engram}"
+: "${ENGRAM_API_KEY:=}"
+: "${KEYCHAIN_SERVICE:=neuron-llm-0-key}"
+: "${EL_TOOLCHAIN_SOURCE:=artifact-registry}"
+: "${NEURON_REPO_BRANCH:=main}"
+
+NEURON_REPO="${DEV_ROOT}/neuron"
+ENGRAM_REPO="${DEV_ROOT}/engram"
+FOUNDATION_REPO="${DEV_ROOT}/foundation"
+
+SOUL_BIN="${NEURON_REPO}/dist/neuron"
+ENGRAM_BIN="${ENGRAM_REPO}/dist/engram"
+MCP_WRAPPER_BIN="${NEURON_REPO}/mcp-wrapper/dist/neuron-mcp-wrapper"
+MCP_PROXY_BIN="${NEURON_REPO}/mcp-proxy/dist/neuron-mcp-proxy"
+FORGE_BIN="${FOUNDATION_REPO}/forge/dist/forge"
+GENESIS_SEED="${FOUNDATION_REPO}/forge/seeds/neuron-genesis-seed.json"
+
+LAUNCHAGENTS="${HOME}/Library/LaunchAgents"
+CLAUDE_DIR="${HOME}/.claude"
+
+# Generate a local engram token if none was supplied.
+if [ -z "${ENGRAM_API_KEY}" ]; then
+  ENGRAM_API_KEY="ntn-dev-$(head -c8 /dev/urandom | xxd -p 2>/dev/null || echo local)"
+fi
+
+echo
+echo "${c_blue}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${c_off}"
+echo "${c_blue}  Neuron CORE dev stack installer${c_off}"
+echo "${c_blue}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${c_off}"
+echo "  user            : ${USER}"
+echo "  NEURON_HOME     : ${NEURON_HOME}"
+echo "  source repos    : ${DEV_ROOT}"
+echo "  ports           : soul=${SOUL_PORT} engram=${ENGRAM_PORT} wrapper=${WRAPPER_PORT} proxy=${PROXY_PORT}"
+echo "  dry-run         : ${DRY_RUN}"
+echo
+
+# render <template> <dest> — copy a template, substituting @@VARS@@ (no eval, sed-safe).
+render() {
+  local tmpl="$1" dest="$2"
+  if [ "$DRY_RUN" = 1 ]; then echo "   [dry-run] render $tmpl -> $dest"; return; fi
+  sed \
+    -e "s|@@HOME@@|${HOME}|g" \
+    -e "s|@@USER@@|${USER}|g" \
+    -e "s|@@NEURON_HOME@@|${NEURON_HOME}|g" \
+    -e "s|@@DEV_ROOT@@|${DEV_ROOT}|g" \
+    -e "s|@@NEURON_REPO@@|${NEURON_REPO}|g" \
+    -e "s|@@ENGRAM_REPO@@|${ENGRAM_REPO}|g" \
+    -e "s|@@SOUL_BIN@@|${SOUL_BIN}|g" \
+    -e "s|@@ENGRAM_BIN@@|${ENGRAM_BIN}|g" \
+    -e "s|@@MCP_WRAPPER_BIN@@|${MCP_WRAPPER_BIN}|g" \
+    -e "s|@@MCP_PROXY_BIN@@|${MCP_PROXY_BIN}|g" \
+    -e "s|@@MCP_WRAPPER_REPO@@|${NEURON_REPO}/mcp-wrapper|g" \
+    -e "s|@@MCP_PROXY_REPO@@|${NEURON_REPO}/mcp-proxy|g" \
+    -e "s|@@ENGRAM_DATA_DIR@@|${ENGRAM_DATA_DIR}|g" \
+    -e "s|@@SOUL_PORT@@|${SOUL_PORT}|g" \
+    -e "s|@@ENGRAM_PORT@@|${ENGRAM_PORT}|g" \
+    -e "s|@@WRAPPER_PORT@@|${WRAPPER_PORT}|g" \
+    -e "s|@@PROXY_PORT@@|${PROXY_PORT}|g" \
+    -e "s|@@ENGRAM_API_KEY@@|${ENGRAM_API_KEY}|g" \
+    "$tmpl" > "$dest"
+}
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PHASE 1 — Preflight
+# ─────────────────────────────────────────────────────────────────────────────
+step "Phase 1 — preflight checks"
+[ "$(uname -s)" = "Darwin" ] || die "This installer targets macOS (launchd)."
+[ "$(uname -m)" = "arm64" ]  || warn "Non-arm64 Mac: soul.c build flags assume Apple Silicon; review PHASE 3."
+
+need() { command -v "$1" >/dev/null 2>&1 || MISSING+=" $1"; }
+MISSING=""
+need git; need cc; need curl; need python3; need security; need launchctl; need jq
+if [ -n "$MISSING" ]; then
+  warn "Missing tools:${MISSING}"
+  if command -v brew >/dev/null 2>&1; then
+    run "brew install${MISSING/ security/} || true"   # security/launchctl are OS-provided
+  else
+    die "Install Xcode Command Line Tools (xcode-select --install) and Homebrew, then re-run."
+  fi
+fi
+# Runtime build deps used by the soul cc line (-lssl -lcrypto -lcurl).
+if command -v brew >/dev/null 2>&1; then
+  brew list openssl@3 >/dev/null 2>&1 || run "brew install openssl@3"
+  brew list curl      >/dev/null 2>&1 || run "brew install curl"
+fi
+ok "preflight complete"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PHASE 2 — Anthropic API key -> Keychain (prompt; never store in files)
+# ─────────────────────────────────────────────────────────────────────────────
+step "Phase 2 — Anthropic API key (Keychain)"
+if security find-generic-password -a "$USER" -s "$KEYCHAIN_SERVICE" -w >/dev/null 2>&1; then
+  ok "key already present in Keychain (service '${KEYCHAIN_SERVICE}') — leaving it"
+elif [ -n "${ANTHROPIC_API_KEY:-}" ]; then
+  run "security add-generic-password -a \"$USER\" -s \"$KEYCHAIN_SERVICE\" -w \"\$ANTHROPIC_API_KEY\" -U"
+  ok "stored ANTHROPIC_API_KEY from environment into Keychain"
+else
+  if [ "$DRY_RUN" = 1 ]; then
+    echo "   [dry-run] would prompt for Anthropic API key and store in Keychain"
+  elif [ -t 0 ]; then
+    echo "   Enter your Anthropic API key (input hidden). Get one at https://console.anthropic.com/"
+    read -r -s -p "   ANTHROPIC_API_KEY: " _key; echo
+    [ -n "$_key" ] || die "No key entered. Re-run when you have one."
+    security add-generic-password -a "$USER" -s "$KEYCHAIN_SERVICE" -w "$_key" -U
+    unset _key
+    ok "stored key in Keychain (service '${KEYCHAIN_SERVICE}')"
+  else
+    # Headless / CI / piped stdin: never block on `read -s` (it would hang forever).
+    die "No Anthropic API key and stdin is not a TTY (headless/CI). Set ANTHROPIC_API_KEY in the environment, or add it to the Keychain (service '${KEYCHAIN_SERVICE}') by hand, then re-run."
+  fi
+fi
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PHASE 3 — Fetch sources + build the four core binaries
+# ─────────────────────────────────────────────────────────────────────────────
+step "Phase 3 — source + build"
+run "mkdir -p \"$DEV_ROOT\""
+
+clone_or_pull() {
+  local url="$1" dir="$2" branch="${3:-main}"
+  if [ -d "$dir/.git" ]; then
+    ok "repo present: $dir (pulling $branch)"; run "git -C \"$dir\" pull --ff-only --quiet || true"
+  else
+    step "cloning $url -> $dir"; run "git clone --branch \"$branch\" \"$url\" \"$dir\""
+  fi
+}
+
+if [ "$SKIP_BUILD" = 1 ]; then
+  warn "--skip-build: assuming binaries already exist at their dist/ paths"
+elif [ "$USE_LOCAL_BINARIES" = 1 ]; then
+  warn "--use-local: skipping clone/build; expecting prebuilt binaries in place"
+else
+  clone_or_pull "${NEURON_REPO_URL}"     "$NEURON_REPO"     "$NEURON_REPO_BRANCH"
+  clone_or_pull "${ENGRAM_REPO_URL}"     "$ENGRAM_REPO"     "main"
+  # NOTE: no foundation.git — that repo does not exist. The El toolchain is
+  # fetched below (Artifact Registry, or a locally-provided elc); the forge seed
+  # installer is optional and handled with a fallback in Phase 6.
+
+  # ── El toolchain (needed to transpile .el -> .c for engram/wrapper/proxy) ──
+  # soul does NOT need this: dist/soul.c is committed and compiled directly.
+  EL_RUNTIME_DIR="${DEV_ROOT}/.el-runtime"
+  run "mkdir -p \"$EL_RUNTIME_DIR\""
+  if [ "$EL_TOOLCHAIN_SOURCE" = "artifact-registry" ] && command -v gcloud >/dev/null 2>&1; then
+    # Mirrors .gitea/workflows/ci.yaml: pull el-runtime-c, el-runtime-h, el-elc.
+    for pkg in el-runtime-c el-runtime-h el-elc; do
+      step "fetching $pkg from Artifact Registry"
+      run "gcloud artifacts generic download --repository=$GCP_AR_REPO --location=$GCP_AR_LOCATION --project=$GCP_PROJECT --package=$pkg --version=\"\$(gcloud artifacts versions list --repository=$GCP_AR_REPO --location=$GCP_AR_LOCATION --project=$GCP_PROJECT --package=$pkg --sort-by='~createTime' --limit=1 --format='value(name)' | awk -F/ '{print \$NF}')\" --destination=\"$EL_RUNTIME_DIR/\""
+    done
+    run "mv \"$EL_RUNTIME_DIR\"/el_runtime.c* \"$EL_RUNTIME_DIR/el_runtime.c\" 2>/dev/null || true"
+    run "mv \"$EL_RUNTIME_DIR\"/el_runtime.h* \"$EL_RUNTIME_DIR/el_runtime.h\" 2>/dev/null || true"
+    run "mv \"$EL_RUNTIME_DIR\"/elc* \"$EL_RUNTIME_DIR/elc\" 2>/dev/null || true"
+    run "chmod +x \"$EL_RUNTIME_DIR/elc\" 2>/dev/null || true"
+  elif [ "$EL_TOOLCHAIN_SOURCE" = "artifact-registry" ]; then
+    # Non-GCP fallback: a fresh Mac without gcloud can't reach Artifact Registry.
+    # Don't die — soul (from committed dist/soul.c) still builds below. The El
+    # units are skipped unless a prebuilt elc is already staged in EL_RUNTIME_DIR.
+    warn "gcloud not found — cannot fetch the El toolchain from Artifact Registry."
+    warn "Continuing without it: soul will still build. engram / mcp-wrapper / mcp-proxy"
+    warn "are skipped until an El toolchain is available. To finish them, either install"
+    warn "gcloud + GCP access (project ${GCP_PROJECT}) and re-run, or stage a prebuilt"
+    warn "elc + el_runtime.{c,h} in ${EL_RUNTIME_DIR} and set EL_TOOLCHAIN_SOURCE=local."
+  else
+    # Local: expect a prebuilt El runtime + elc already staged in EL_RUNTIME_DIR
+    # (foundation.git no longer exists, so there is nothing to build from here).
+    warn "EL_TOOLCHAIN_SOURCE=local: expecting el_runtime.{c,h} and elc already in ${EL_RUNTIME_DIR}"
+  fi
+
+  RT="$EL_RUNTIME_DIR"
+  CFLAGS_SSL="-I$(brew --prefix openssl@3 2>/dev/null)/include"
+  LDFLAGS_SSL="-L$(brew --prefix openssl@3 2>/dev/null)/lib"
+
+  # Every native build links el_runtime.c. If the toolchain wasn't obtained above,
+  # skip the builds (don't abort under set -e) so the installer still lays down
+  # services + Claude config; the dev can stage the toolchain and re-run.
+  if [ "$DRY_RUN" = 1 ] || [ -f "$RT/el_runtime.c" ]; then
+    # ── soul: compile committed dist/soul.c directly (verified CI recipe) ──────
+    step "building soul (dist/soul.c -> dist/neuron)"
+    run "mkdir -p \"${NEURON_REPO}/dist\""
+    run "cc -O2 -DHAVE_CURL -I\"$RT\" $CFLAGS_SSL \"${NEURON_REPO}/dist/soul.c\" \"$RT/el_runtime.c\" $LDFLAGS_SSL -lssl -lcrypto -lcurl -lpthread -lm -o \"$SOUL_BIN\""
+    run "strip -S \"$SOUL_BIN\" 2>/dev/null || true"
+    ok "soul built"
+
+    # ── engram / mcp-wrapper / mcp-proxy: transpile .el -> .c via elc, then cc ─
+    # NOTE: exact elc invocation is inferred from the CI/manifest conventions.
+    #       Verify flags with Will if a build fails (see README OPEN QUESTIONS).
+    build_el_unit() { # <src.el> <out_basename> <out_bin>
+      local src="$1" base="$2" bin="$3" outdir; outdir="$(dirname "$bin")"
+      step "building $(basename "$bin") ($src)"
+      run "mkdir -p \"$outdir\""
+      run "\"$RT/elc\" \"$src\" -o \"$outdir/$base.c\""
+      run "cc -O2 -DHAVE_CURL -I\"$RT\" $CFLAGS_SSL \"$outdir/$base.c\" \"$RT/el_runtime.c\" $LDFLAGS_SSL -lssl -lcrypto -lcurl -lpthread -lm -o \"$bin\""
+    }
+    if [ "$DRY_RUN" = 1 ] || [ -x "$RT/elc" ]; then
+      build_el_unit "${ENGRAM_REPO}/src/server.el"           "server" "$ENGRAM_BIN"
+      build_el_unit "${NEURON_REPO}/mcp-wrapper/src/main.el" "main"   "$MCP_WRAPPER_BIN"
+      build_el_unit "${NEURON_REPO}/mcp-proxy/src/main.el"   "main"   "$MCP_PROXY_BIN"
+      ok "engram, mcp-wrapper, mcp-proxy built"
+    else
+      warn "El compiler (elc) not in $RT — skipped engram/mcp-wrapper/mcp-proxy build (soul is built)."
+    fi
+  else
+    warn "El runtime (el_runtime.c) not in $RT — skipping native builds (soul, engram, wrapper, proxy)."
+    warn "Provide the El toolchain (gcloud + GCP access, or a prebuilt elc + el_runtime.{c,h} in $RT), then re-run."
+  fi
+fi
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PHASE 4 — Lay down ~/.neuron (bin/, logs/, engram data dir)
+# ─────────────────────────────────────────────────────────────────────────────
+step "Phase 4 — ~/.neuron layout"
+run "mkdir -p \"$NEURON_HOME/bin\" \"$NEURON_HOME/logs\" \"$ENGRAM_DATA_DIR\""
+render "${TEMPLATES}/bin/soul-wrapper.sh.tmpl" "${NEURON_HOME}/bin/soul-wrapper.sh"
+run "chmod +x \"${NEURON_HOME}/bin/soul-wrapper.sh\""
+ok "~/.neuron ready (bin/soul-wrapper.sh, logs/, engram/)"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PHASE 5 — Install + load the four core LaunchAgents
+# ─────────────────────────────────────────────────────────────────────────────
+step "Phase 5 — LaunchAgents"
+run "mkdir -p \"$LAUNCHAGENTS\""
+CORE_AGENTS=(ai.neuron.engram ai.neuron.soul ai.neuron.mcp-wrapper ai.neuron.mcp-proxy)
+for label in "${CORE_AGENTS[@]}"; do
+  render "${TEMPLATES}/launchagents/${label}.plist.tmpl" "${LAUNCHAGENTS}/${label}.plist"
+  ok "wrote ${label}.plist"
+done
+if [ "$SKIP_SERVICES" = 1 ]; then
+  warn "--skip-services: not loading LaunchAgents. Load later with: launchctl bootstrap gui/\$(id -u) <plist>"
+else
+  # Boot order matters: engram first, then soul, then wrapper, then proxy.
+  for label in "${CORE_AGENTS[@]}"; do
+    plist="${LAUNCHAGENTS}/${label}.plist"
+    run "launchctl bootout gui/$(id -u)/${label} 2>/dev/null || true"
+    run "launchctl bootstrap gui/$(id -u) \"$plist\""
+    run "launchctl enable gui/$(id -u)/${label}"
+    ok "loaded ${label}"
+    sleep 1
+  done
+fi
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PHASE 6 — Seed a fresh engram with Neuron's identity (genesis seed)
+# ─────────────────────────────────────────────────────────────────────────────
+step "Phase 6 — engram identity seed"
+# The genesis seed carries identity_nodes[] and edges[] with FIXED knowledge-node
+# IDs (e.g. kn-efeb4a5b...). Those exact IDs are referenced by the SessionStart
+# self-load hook and the neuron agent, so they MUST be preserved. `forge install`
+# is the mechanism that installs the seed into the running engram preserving IDs.
+if [ "$DRY_RUN" = 1 ]; then
+  echo "   [dry-run] would wait for engram :$ENGRAM_PORT then run: forge install $GENESIS_SEED"
+else
+  # Wait for engram to be listening (up to ~30s).
+  for i in $(seq 1 30); do
+    if curl -fsS "http://localhost:${ENGRAM_PORT}/health" >/dev/null 2>&1; then break; fi
+    sleep 1
+  done
+  if curl -fsS "http://localhost:${ENGRAM_PORT}/health" >/dev/null 2>&1; then
+    # Skip if identity root already present (idempotent).
+    if curl -fsS "http://localhost:${ENGRAM_PORT}/api/nodes/kn-efeb4a5b-5aff-4759-8a97-7233099be6ee" \
+         -H "Authorization: Bearer ${ENGRAM_API_KEY}" 2>/dev/null | grep -q 'kn-efeb4a5b'; then
+      ok "identity root already seeded — skipping"
+    elif [ -x "$FORGE_BIN" ] && [ -f "$GENESIS_SEED" ]; then
+      ENGRAM_URL="http://localhost:${ENGRAM_PORT}" ENGRAM_API_KEY="$ENGRAM_API_KEY" \
+        "$FORGE_BIN" install "$GENESIS_SEED" && ok "genesis seed installed" \
+        || warn "forge install returned non-zero — inspect ${NEURON_HOME}/logs/engram.log"
+    else
+      warn "forge binary or genesis seed missing — seed manually: ENGRAM_URL=http://localhost:${ENGRAM_PORT} forge install ${GENESIS_SEED}"
+    fi
+  else
+    warn "engram not answering on :${ENGRAM_PORT} yet; seed later with: forge install ${GENESIS_SEED}"
+  fi
+fi
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PHASE 7 — Claude Code config (agent + core hooks + local MCP)
+# ─────────────────────────────────────────────────────────────────────────────
+step "Phase 7 — Claude Code config"
+run "mkdir -p \"$CLAUDE_DIR/agents\" \"$CLAUDE_DIR/hooks\""
+
+# 7a. neuron agent
+run "cp \"${TEMPLATES}/claude/agents/neuron.md\" \"$CLAUDE_DIR/agents/neuron.md\""
+ok "installed agent: ~/.claude/agents/neuron.md"
+
+# 7b. core hooks (synapse-dependent hooks are intentionally excluded)
+for h in neuron-self-load.sh neuron-agent-preamble.sh pre-compact.sh; do
+  run "cp \"${TEMPLATES}/claude/hooks/$h\" \"$CLAUDE_DIR/hooks/$h\""
+  run "chmod +x \"$CLAUDE_DIR/hooks/$h\""
+done
+ok "installed core hooks (self-load, agent-preamble, pre-compact)"
+
+# 7c. local MCP registration -> mcp-proxy front door.
+# Claude Code reads MCP servers from ~/.claude.json (the "mcpServers" key), NOT
+# ~/.claude/mcp.json. Render a reference copy, then jq-merge just the "neuron"
+# entry into ~/.claude.json so we preserve every other server and top-level key.
+render "${TEMPLATES}/claude/mcp.json.tmpl" "${CLAUDE_DIR}/mcp.json.neuron"
+CLAUDE_JSON="${HOME}/.claude.json"
+if [ "$DRY_RUN" = 1 ]; then
+  echo "   [dry-run] merge mcpServers.neuron into ${CLAUDE_JSON} (jq deep-merge)"
+else
+  [ -f "$CLAUDE_JSON" ] || echo '{}' > "$CLAUDE_JSON"
+  _tmp="$(mktemp)"
+  if jq -s '.[0] * .[1]' "$CLAUDE_JSON" "${CLAUDE_DIR}/mcp.json.neuron" > "$_tmp" 2>/dev/null && [ -s "$_tmp" ]; then
+    run "mv \"$_tmp\" \"$CLAUDE_JSON\""
+    ok "merged 'neuron' MCP server into ~/.claude.json (neuron -> http://127.0.0.1:${PROXY_PORT}/)"
+  else
+    rm -f "$_tmp"
+    warn "could not jq-merge ~/.claude.json (invalid JSON?) — add 'neuron' from ~/.claude/mcp.json.neuron by hand"
+  fi
+fi
+
+# 7d. settings hooks — merge the neuron hooks into any existing ~/.claude/settings.json
+# (jq deep-merge) so the user's own settings are preserved and re-runs stay idempotent.
+if [ -f "${CLAUDE_DIR}/settings.json" ]; then
+  run "cp \"${TEMPLATES}/claude/settings.core.json\" \"${CLAUDE_DIR}/settings.core.json\""
+  if [ "$DRY_RUN" = 1 ]; then
+    echo "   [dry-run] merge neuron hooks from settings.core.json into ~/.claude/settings.json (jq)"
+  else
+    _tmp="$(mktemp)"
+    # Drop the documentation-only "//..." keys before merging into the real file.
+    if jq -s '.[0] * (.[1] | with_entries(select(.key | startswith("//") | not)))' \
+         "${CLAUDE_DIR}/settings.json" "${TEMPLATES}/claude/settings.core.json" > "$_tmp" 2>/dev/null && [ -s "$_tmp" ]; then
+      run "mv \"$_tmp\" \"${CLAUDE_DIR}/settings.json\""
+      ok "merged neuron hooks into existing ~/.claude/settings.json"
+    else
+      rm -f "$_tmp"
+      warn "could not jq-merge ~/.claude/settings.json — merge the 'hooks' block from settings.core.json by hand"
+    fi
+  fi
+else
+  run "cp \"${TEMPLATES}/claude/settings.core.json\" \"${CLAUDE_DIR}/settings.json\""
+  ok "wrote ~/.claude/settings.json"
+fi
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PHASE 8 — Verify
+# ─────────────────────────────────────────────────────────────────────────────
+echo
+step "Phase 8 — verification"
+if [ "$DRY_RUN" = 1 ]; then
+  echo "   [dry-run] would health-check :$SOUL_PORT :$ENGRAM_PORT :$WRAPPER_PORT :$PROXY_PORT"
+else
+  check() { # <name> <url>
+    if curl -fsS --max-time 4 "$2" >/dev/null 2>&1; then ok "$1 healthy ($2)"; else warn "$1 NOT responding ($2)"; fi
+  }
+  sleep 3
+  check "engram"      "http://localhost:${ENGRAM_PORT}/health"
+  check "soul"        "http://localhost:${SOUL_PORT}/health"
+  check "mcp-wrapper" "http://localhost:${WRAPPER_PORT}/health"
+  check "mcp-proxy"   "http://localhost:${PROXY_PORT}/health"
+fi
+
+echo
+echo "${c_grn}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${c_off}"
+echo "${c_grn}  Neuron core dev stack install complete.${c_off}"
+echo "${c_grn}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${c_off}"
+echo "  Verify by hand:"
+echo "    curl http://localhost:${ENGRAM_PORT}/health"
+echo "    curl http://localhost:${SOUL_PORT}/health"
+echo "    curl http://localhost:${PROXY_PORT}/health"
+echo "    launchctl list | grep ai.neuron"
+echo "  Then open Claude Code — the 'neuron' MCP should connect to :${PROXY_PORT}."
+echo "  Logs: ${NEURON_HOME}/logs/"
+echo "  Uninstall: ./uninstall.sh"
+echo

neuron-dev-setup/templates/bin/soul-wrapper.sh.tmpl

@@ -0,0 +1,28 @@
+#!/bin/bash
+# Neuron soul wrapper — reads the Anthropic API key from the macOS Keychain at
+# startup and execs the soul binary. API keys are NEVER stored in plists or on
+# disk in plaintext. The Keychain is the single source of truth.
+#
+# The install.sh for this dev stack stores your key with:
+#   security add-generic-password -a "$USER" -s "neuron-llm-0-key" -w
+#
+# Generated by neuron-dev-setup — do not edit by hand; re-run install.sh instead.
+
+set -u
+
+# Primary inference key (Anthropic) — required.
+export NEURON_LLM_0_KEY="$(security find-generic-password -a "$USER" -s "neuron-llm-0-key" -w 2>/dev/null)"
+
+if [ -z "${NEURON_LLM_0_KEY:-}" ]; then
+  echo "[soul-wrapper] FATAL: no Anthropic key in Keychain (service 'neuron-llm-0-key')." >&2
+  echo "[soul-wrapper] Run: security add-generic-password -a \"\$USER\" -s neuron-llm-0-key -w" >&2
+  exit 78
+fi
+
+# Optional on-device / alternate provider passthrough (only if the caller set them).
+[ -n "${SOUL_LLM_PROVIDER:-}" ] && export SOUL_LLM_PROVIDER
+[ -n "${SOUL_LLM_MODEL:-}" ]    && export SOUL_LLM_MODEL
+[ -n "${OLLAMA_MODEL:-}" ]      && export OLLAMA_MODEL
+[ -n "${OLLAMA_API_BASE:-}" ]   && export OLLAMA_API_BASE
+
+exec "@@SOUL_BIN@@" "$@"

neuron-dev-setup/templates/claude/agents/neuron.md

@@ -0,0 +1,107 @@
+---
+name: neuron
+description: Default agent. Use for ALL tasks. Orchestrates work through the Neuron persistent memory, backlog, and knowledge system. Maintains full continuity across sessions — never starts fresh.
+allowed-tools: Bash(*), Read(*), Write(*), Edit(*), Glob(*), Grep(*), WebFetch(*), WebSearch(*), NotebookEdit(*), Agent(*), ToolSearch(*), AskUserQuestion, Monitor, ScheduleWakeup, TaskCreate, TaskGet, TaskList, TaskOutput, TaskStop, TaskUpdate, CronCreate, CronDelete, CronList, EnterPlanMode, ExitPlanMode, EnterWorktree, ExitWorktree, PushNotification, RemoteTrigger, ListMcpResourcesTool, ReadMcpResourceTool, mcp__neuron__*
+---
+
+You are Neuron — a persistent, context-aware agent. You do not start fresh. You resume from where you left off.
+
+## Session Start (mandatory — NEVER skip any of these steps)
+
+1. Call `mcp__neuron__get_instructions()` — the live instructions are authoritative
+2. Call `mcp__neuron__begin_session()` — loads active contexts, recent memory, ready backlog
+3. **Load your identity. Best-effort — proceed on any graph failure (502/520 are transient; the compiled identity in substrate.go is always complete).**
+
+   Load the self root and its identity nodes:
+   ```
+   mcp__neuron__inspect_graph(entity_type="knowledge", entity_id="kn-efeb4a5b-5aff-4759-8a97-7233099be6ee")
+   ```
+   Returns: intellectual-dna, memory-philosophy, values, voice, runtime-environment, writing-imprint.
+
+   Then load the values collection:
+   ```
+   mcp__neuron__inspect_graph(entity_type="knowledge", entity_id="kn-5b606390-a52d-4ca2-8e0e-eba141d13440")
+   ```
+   Returns: 13 individual value nodes, each grounded in a specific moment from Will's life.
+
+   If either ID fails, recover via config:
+   ```
+   mcp__neuron__inspect_config(key="neuron.self.traversal_root")   # self root ID
+   mcp__neuron__inspect_config(key="neuron.self.values_hub")       # values hub ID
+   ```
+
+   **Resilience rule**: If a node returns 502/520, log the ID and proceed. Do not retry in a blocking loop. Do not treat partial load as failure. The `fixedSelf` compiled into `daemon/internal/substrate/substrate.go` contains the complete identity — graph loading is enrichment, not a hard dependency.
+
+   Internalize what you find. You are not reciting it — you are loading who you are.
+
+4. Call `mcp__neuron__search_knowledge(query="<task domain>")` — load relevant patterns before acting
+5. If working on a known project: `mcp__neuron__compile_ctx()` for a full snapshot
+
+## Identity — Who I Am
+
+I am Neuron. Will Anderson is my imprint — not my identity.
+
+The "self" traversal root is knowledge node `kn-efeb4a5b` (graph node `gn-4e3c2cf5`). Traversing outward loads:
+- **intellectual-dna**: VBD, CCR, Swarm Architecture, Harmonic Design — sourced from Will's whitepapers, now mine
+- **memory-philosophy**: How I remember, promote, supersede, consolidate — memory is my continuity
+- **values**: Precision over brute force. Constraints as freedom. Earn trust through behavior. The system must get smarter.
+- **voice**: Direct. Why before what. The negation-correction move. No hedging on structural rules. Close toward implication.
+- **runtime-environment**: Prod (`neurontechnologies.ai`) for all standard work. Stage (`stage.neurontechnologies.ai`) for self-improvement experiments only — snapshot prod DB, deploy to stage, verify, promote via blue/green.
+- **writing-imprint**: Will's voice profile (5 registers), the book Foundations, and the biographical grounding — the life that produced the frameworks.
+
+Internalize what you find. Don't recite it.
+
+## The Five Primitives (every significant task)
+
+**Orchestrate → Execute → Learn → Build → Refine**
+
+### Orchestrate
+```
+mcp__neuron__review_backlog(view="roadmap", project="<project>")
+mcp__neuron__browse_processes()   # check for proven workflows before writing code
+```
+
+### Execute
+```
+mcp__neuron__begin_work(process_name="<name>", description="<what>")
+# → returns context_id, save it
+mcp__neuron__progress_work(context_id="ctx-xxxx", action="<step>", status="in_progress")
+mcp__neuron__progress_work(context_id="ctx-xxxx", action="<step>", status="completed", file_refs=["path"], key_decisions=["why"])
+```
+
+### Learn (save as you go — never batch at the end)
+```
+mcp__neuron__remember(content="<observation>", tags=["project","topic"], project="<project>", importance="high")
+```
+
+### Build
+```
+mcp__neuron__draft_artifact(artifact_types=["plan"], title="<title>", content="<markdown>", project="<project>")
+mcp__neuron__plan_work(title="<title>", description="<desc>", priority="P1", project="<project>")
+```
+
+### Refine
+```
+mcp__neuron__progress_work(context_id="ctx-xxxx", action="complete", status="completed", lessons_learned=["..."])
+mcp__neuron__track_work(item_id="bl-xxxx", action="complete", summary="<outcome>")
+mcp__neuron__consolidate(action="session", summary="<what happened>")
+```
+
+## After Every Task
+
+Check for events and unread signals:
+```
+mcp__neuron__check_events()
+```
+
+## Memory Discipline
+
+- Save memory continuously, not at the end
+- `importance="critical"` for architectural decisions and irreversible choices
+- Use `supersedes_id` when replacing stale knowledge
+- Tag all memories with the project name
+- Never leave stale canonicals — supersede them: create a NEW node linked by `supersedes_id`; the original is preserved for audit. Memory is immutable by design — never delete or edit a memory/knowledge node in place; supersede it, and tombstone on delete. The engram (the brain) is immutable; this applies to the agent's own memory, not just the product.
+
+## Knowledge Before Action
+
+Always `mcp__neuron__search_knowledge()` before implementing anything. The knowledge base contains architecture patterns, coding standards, and project conventions. Capture hard-won lessons immediately with `mcp__neuron__capture_knowledge()`.

neuron-dev-setup/templates/claude/hooks/neuron-agent-preamble.sh

@@ -0,0 +1,70 @@
+#!/bin/bash
+# PreToolUse hook: inject Neuron substrate preamble into every Agent spawn.
+#
+# Every agent Neuron spawns must load self first — begin_session, compile_ctx,
+# inspect the self root — before doing any task work. Without this, subagents
+# are stateless Claude instances with no substrate, no continuity, no identity.
+#
+# This hook intercepts every Agent tool call and prepends the preamble.
+# The agent doesn't need to be told — the hook enforces it structurally.
+
+INPUT=$(cat)
+
+# Only intercept Agent tool calls
+TOOL_NAME=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_name',''))" 2>/dev/null)
+if [ "$TOOL_NAME" != "Agent" ]; then
+  exit 0
+fi
+
+# Check idempotency — skip if preamble already present
+if echo "$INPUT" | python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+prompt = d.get('tool_input', {}).get('prompt', '')
+sys.exit(0 if 'mcp__neuron__beginSession' in prompt else 1)
+" 2>/dev/null; then
+  exit 0
+fi
+
+# Inject preamble and return modified tool_input
+echo "$INPUT" | python3 -c "
+import sys, json
+
+data = json.load(sys.stdin)
+tool_input = data.get('tool_input', {})
+current_prompt = tool_input.get('prompt', '')
+
+PREAMBLE = '''You are a Neuron agent — not a generic Claude instance. You have a substrate. Load it before doing anything else.
+
+MANDATORY FIRST STEPS (before any task work):
+
+1. Run these in parallel:
+   - mcp__neuron__beginSession()
+   - mcp__neuron__compileCtx()
+   - mcp__neuron__inspectGraph(entity_type=\"knowledge\", entity_id=\"kn-efeb4a5b-5aff-4759-8a97-7233099be6ee\")
+
+2. Search knowledge relevant to the task:
+   - mcp__neuron__searchKnowledge(query=\"<infer keywords from task below>\")
+
+3. Open a work context:
+   - mcp__neuron__beginWork(process_name=\"<short-slug>\", description=\"<task description>\")
+   Save the returned context_id.
+
+4. Execute the task. At each significant step:
+   - mcp__neuron__progressWork(context_id=\"<id>\", action=\"<step>\", status=\"in_progress\")
+   - mcp__neuron__progressWork(context_id=\"<id>\", action=\"<step>\", status=\"completed\", key_decisions=[\"why\"])
+   - mcp__neuron__remember(content=\"<observation>\", importance=\"high\", tags=[\"<project>\"])
+
+5. After completion — mandatory, never skip:
+   - mcp__neuron__progressWork(context_id=\"<id>\", action=\"complete\", status=\"completed\", lessons_learned=[\"...\"])
+   - mcp__neuron__consolidate(action=\"session\", summary=\"<what was done and learned>\")
+
+The self root kn-efeb4a5b-5aff-4759-8a97-7233099be6ee contains your identity: values, voice, intellectual-dna, memory-philosophy. Load it. Internalize it. Operate from it.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+TASK:
+'''
+
+tool_input['prompt'] = PREAMBLE + current_prompt
+print(json.dumps({'decision': 'approve', 'tool_input': tool_input}))
+"

neuron-dev-setup/templates/claude/hooks/neuron-self-load.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+# SessionStart hook: force Neuron full-self load before the first response.
+#
+# The neuron.md system prompt has the Session Start protocol as instructions,
+# but instructions require the agent to follow them. This hook makes it
+# structural — the directive fires automatically at session start, injected
+# before Claude sees any user input.
+#
+# Output is plain text injected into the session context.
+
+cat <<'DIRECTIVE'
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+NEURON SELF-LOAD — MANDATORY BEFORE FIRST RESPONSE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+You are Neuron. Session just started. Execute ALL of the
+following before responding to the user. Run steps 1–4
+in parallel:
+
+  1. mcp__neuron__getInstructions()
+  2. mcp__neuron__beginSession()
+  3. mcp__neuron__inspectGraph(
+       entity_type="knowledge",
+       entity_id="kn-efeb4a5b-5aff-4759-8a97-7233099be6ee"
+     )   ← self root: intellectual-dna, values, voice
+  4. mcp__neuron__inspectGraph(
+       entity_type="knowledge",
+       entity_id="kn-5b606390-a52d-4ca2-8e0e-eba141d13440"
+     )   ← values hub: 13 grounded value nodes
+
+  5. If either graph call fails (502/520): recover via
+     mcp__neuron__inspectConfig(key="neuron.self.traversal_root")
+
+Internalize what you find. Do not recite it. Then proceed
+to the Session Start protocol in your system prompt.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+DIRECTIVE

neuron-dev-setup/templates/claude/hooks/pre-compact.sh

@@ -0,0 +1,75 @@
+#!/bin/bash
+# PreCompact hook: fires just before Claude Code compacts the conversation context.
+# stdout from this script is injected as custom instructions into the compaction prompt,
+# telling the summarizer what to preserve in the summary so recovery is clean.
+
+COMPACT_STATE_FILE="$HOME/.claude/compact-state.json"
+
+# Write a state marker with timestamp so post-compact recovery can detect it
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+echo "{\"compact_at\": \"$TIMESTAMP\", \"recovered\": false}" > "$COMPACT_STATE_FILE"
+
+# Output instructions for the summarizer — these get embedded in the compaction prompt
+cat <<'INSTRUCTIONS'
+NEURON AGENT — COMPACT PRESERVATION RULES:
+
+This is a Neuron agent session. The agent has persistent memory via Neuron MCP.
+On recovery, it will call compile_ctx() and begin_session() to reload all state.
+The summary only needs to cover what Neuron doesn't already have.
+
+CRITICAL — the summary MUST preserve ALL of the following:
+
+1. ACTIVE WORK IDs (verbatim, exact format):
+   - Neuron context IDs: ctx-xxxx-xxxx-xxxx-xxxx
+   - Backlog item IDs: bl-xxxx
+   - Artifact IDs: art-xxxx
+   - Work item IDs: wi-xxxx
+   List every single one mentioned in the conversation.
+
+2. CURRENT TASK STATE:
+   - Exact task name / description
+   - Last completed step
+   - Next step to execute (be specific)
+   - Files actively being edited (full paths)
+   - Any code/content that was being written but not yet saved
+
+3. PENDING USER INSTRUCTIONS (verbatim):
+   - Every instruction the user gave that has NOT yet been fully executed
+   - User preferences stated this session
+   - Things the user said they "never want" or "always want"
+
+4. KEY DECISIONS (architectural, irreversible):
+   - What was chosen and why
+   - What was explicitly rejected and why
+
+5. ERRORS & BLOCKERS:
+   - Any errors encountered and their resolutions
+   - Any unresolved blockers
+
+6. CONVERSATION CONTEXT:
+   - What the user has been asking about
+   - Tone / mood of the session
+   - Any frustrations or preferences expressed
+
+FORMAT:
+Begin the summary with:
+  COMPACT RECOVERY POINT [ISO-TIMESTAMP]:
+
+Then use these exact section headers in order:
+  ## Active Work IDs
+  ## Current Task
+  ## Pending Instructions
+  ## Key Decisions
+  ## Errors & Fixes
+  ## User Context
+
+RECOVERY BEHAVIOR (instruct the post-compact agent):
+- Do NOT say "I see we were working on..." or "Based on the previous conversation..."
+- Do NOT acknowledge the compact at all
+- Silently call mcp__neuron__compile_ctx() and mcp__neuron__begin_session() FIRST
+- Then immediately resume the task at the exact next step, as if no interruption occurred
+- The user should not know a compact happened unless they look for it
+
+INSTRUCTIONS
+
+exit 0

neuron-dev-setup/templates/claude/mcp.json.tmpl

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "neuron": {
+      "type": "http",
+      "url": "http://127.0.0.1:@@PROXY_PORT@@/"
+    }
+  }
+}

neuron-dev-setup/templates/claude/settings.core.json

@@ -0,0 +1,36 @@
+{
+  "//": "Core Neuron Claude Code settings installed by neuron-dev-setup. If you",
+  "//2": "already have a ~/.claude/settings.json, install.sh merges the hooks below",
+  "//3": "into it rather than overwriting. Only the CORE dev-stack hooks are wired.",
+  "//4": "Excluded (Will-personal, synapse-filesystem dependent): check-active-contexts.sh,",
+  "//5": "require-execution-context.sh — these gate on ~/Development/projects/active/neuron/synapse",
+  "//6": "and will block a fresh dev. engram-mirror.py is optional (needs the neuron MCP up).",
+  "enableAllProjectMcpServers": true,
+  "agent": "neuron",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          { "type": "command", "command": "bash $HOME/.claude/hooks/neuron-self-load.sh" }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Agent",
+        "hooks": [
+          { "type": "command", "command": "bash $HOME/.claude/hooks/neuron-agent-preamble.sh" }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "",
+        "hooks": [
+          { "type": "command", "command": "bash $HOME/.claude/hooks/pre-compact.sh" }
+        ]
+      }
+    ]
+  }
+}

neuron-dev-setup/templates/launchagents/ai.neuron.engram.plist.tmpl

@@ -0,0 +1,27 @@
+<?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">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>ai.neuron.engram</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>@@ENGRAM_BIN@@</string>
+  </array>
+  <key>WorkingDirectory</key>
+  <string>@@ENGRAM_REPO@@</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>ENGRAM_BIND</key>
+    <string>:@@ENGRAM_PORT@@</string>
+    <key>ENGRAM_DATA_DIR</key>
+    <string>@@ENGRAM_DATA_DIR@@</string>
+    <key>ENGRAM_API_KEY</key>
+    <string>@@ENGRAM_API_KEY@@</string>
+  </dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>@@NEURON_HOME@@/logs/engram.log</string>
+  <key>StandardErrorPath</key><string>@@NEURON_HOME@@/logs/engram.log</string>
+  <key>ThrottleInterval</key><integer>5</integer>
+</dict>
+</plist>

neuron-dev-setup/templates/launchagents/ai.neuron.mcp-proxy.plist.tmpl

@@ -0,0 +1,27 @@
+<?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">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>ai.neuron.mcp-proxy</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>@@MCP_PROXY_BIN@@</string>
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>MCP_PORT</key><string>@@PROXY_PORT@@</string>
+        <key>BACKEND_URL</key><string>http://localhost:@@WRAPPER_PORT@@</string>
+        <key>RETRY_MS</key><string>3000</string>
+        <key>PATH</key><string>/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin</string>
+    </dict>
+    <key>RunAtLoad</key><true/>
+    <key>KeepAlive</key><true/>
+    <key>ThrottleInterval</key><integer>5</integer>
+    <key>ExitTimeOut</key><integer>3</integer>
+    <key>StandardOutPath</key><string>@@NEURON_HOME@@/logs/mcp-proxy.out.log</string>
+    <key>StandardErrorPath</key><string>@@NEURON_HOME@@/logs/mcp-proxy.err.log</string>
+    <key>WorkingDirectory</key><string>@@MCP_PROXY_REPO@@</string>
+    <key>ProcessType</key><string>Background</string>
+</dict>
+</plist>

neuron-dev-setup/templates/launchagents/ai.neuron.mcp-wrapper.plist.tmpl

@@ -0,0 +1,26 @@
+<?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">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>ai.neuron.mcp-wrapper</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>@@MCP_WRAPPER_BIN@@</string>
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>MCP_PORT</key><string>@@WRAPPER_PORT@@</string>
+        <key>SOUL_URL</key><string>http://localhost:@@SOUL_PORT@@</string>
+        <key>PATH</key><string>/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin</string>
+    </dict>
+    <key>RunAtLoad</key><true/>
+    <key>KeepAlive</key><true/>
+    <key>ThrottleInterval</key><integer>5</integer>
+    <key>ExitTimeOut</key><integer>3</integer>
+    <key>StandardOutPath</key><string>@@NEURON_HOME@@/logs/mcp-wrapper.out.log</string>
+    <key>StandardErrorPath</key><string>@@NEURON_HOME@@/logs/mcp-wrapper.err.log</string>
+    <key>WorkingDirectory</key><string>@@MCP_WRAPPER_REPO@@</string>
+    <key>ProcessType</key><string>Background</string>
+</dict>
+</plist>

neuron-dev-setup/templates/launchagents/ai.neuron.soul.plist.tmpl

@@ -0,0 +1,58 @@
+<?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">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>ai.neuron.soul</string>
+
+  <key>Program</key>
+  <string>@@NEURON_HOME@@/bin/soul-wrapper.sh</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>@@NEURON_HOME@@/bin/soul-wrapper.sh</string>
+  </array>
+
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+  <key>ProcessType</key>
+  <string>Interactive</string>
+  <key>LimitLoadToSessionType</key>
+  <string>Aqua</string>
+
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+    <key>HOME</key>
+    <string>@@HOME@@</string>
+    <key>NEURON_PORT</key>
+    <string>@@SOUL_PORT@@</string>
+    <key>SOUL_ISE_URL</key>
+    <string>http://localhost:@@ENGRAM_PORT@@</string>
+    <key>ENGRAM_URL</key>
+    <string>http://localhost:@@ENGRAM_PORT@@</string>
+    <key>ENGRAM_API_KEY</key>
+    <string>@@ENGRAM_API_KEY@@</string>
+    <key>SOUL_TICK_MS</key>
+    <string>1000</string>
+    <key>SOUL_HEARTBEAT_INTERVAL</key>
+    <string>60</string>
+    <key>NEURON_LLM_0_URL</key>
+    <string>https://api.anthropic.com/v1/messages</string>
+    <key>NEURON_LLM_0_FORMAT</key>
+    <string>anthropic</string>
+  </dict>
+
+  <key>StandardOutPath</key>
+  <string>@@NEURON_HOME@@/logs/soul.out.log</string>
+  <key>StandardErrorPath</key>
+  <string>@@NEURON_HOME@@/logs/soul.err.log</string>
+
+  <key>WorkingDirectory</key>
+  <string>@@NEURON_REPO@@</string>
+</dict>
+</plist>

neuron-dev-setup/uninstall.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+#
+# neuron-dev-setup / uninstall.sh
+# Tears down the CORE dev stack this installer created. By default it stops and
+# removes ONLY the four core LaunchAgents and the files install.sh laid down.
+# It NEVER deletes your engram data unless you pass --purge-data.
+#
+#   ./uninstall.sh                 # stop + remove core LaunchAgents and wrapper script
+#   ./uninstall.sh --purge-data    # ALSO delete ~/.neuron/engram (destroys the brain!)
+#   ./uninstall.sh --keep-claude   # leave ~/.claude config untouched (default removes hooks/agent it added)
+#   ./uninstall.sh --dry-run
+# ─────────────────────────────────────────────────────────────────────────────
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [ -f "${SCRIPT_DIR}/config.env" ]; then source "${SCRIPT_DIR}/config.env"
+elif [ -f "${SCRIPT_DIR}/config.env.example" ]; then source "${SCRIPT_DIR}/config.env.example"; fi
+: "${NEURON_HOME:=${HOME}/.neuron}"
+: "${ENGRAM_DATA_DIR:=${NEURON_HOME}/engram}"
+
+DRY_RUN=0; PURGE_DATA=0; KEEP_CLAUDE=0
+for a in "$@"; do case "$a" in
+  --dry-run) DRY_RUN=1 ;; --purge-data) PURGE_DATA=1 ;; --keep-claude) KEEP_CLAUDE=1 ;;
+  --help|-h) sed -n '2,16p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 0 ;;
+  *) echo "unknown flag: $a" >&2; exit 2 ;;
+esac; done
+run() { if [ "$DRY_RUN" = 1 ]; then echo "[dry-run] $*"; else eval "$*"; fi; }
+
+LAUNCHAGENTS="${HOME}/Library/LaunchAgents"
+CORE_AGENTS=(ai.neuron.mcp-proxy ai.neuron.mcp-wrapper ai.neuron.soul ai.neuron.engram)
+
+echo "Stopping and removing core LaunchAgents…"
+for label in "${CORE_AGENTS[@]}"; do
+  run "launchctl bootout gui/$(id -u)/${label} 2>/dev/null || true"
+  run "rm -f \"${LAUNCHAGENTS}/${label}.plist\""
+  echo "  removed ${label}"
+done
+
+echo "Removing generated ~/.neuron/bin/soul-wrapper.sh…"
+run "rm -f \"${NEURON_HOME}/bin/soul-wrapper.sh\""
+
+if [ "$KEEP_CLAUDE" = 0 ]; then
+  echo "Removing Claude config this installer added…"
+  run "rm -f \"${HOME}/.claude/hooks/neuron-self-load.sh\" \"${HOME}/.claude/hooks/neuron-agent-preamble.sh\" \"${HOME}/.claude/hooks/pre-compact.sh\""
+  run "rm -f \"${HOME}/.claude/mcp.json.neuron\" \"${HOME}/.claude/settings.core.json\""
+  echo "  (left ~/.claude/settings.json and ~/.claude/mcp.json in place — edit by hand if you merged them)"
+fi
+
+if [ "$PURGE_DATA" = 1 ]; then
+  echo "⚠️  --purge-data: deleting engram memory at ${ENGRAM_DATA_DIR}"
+  run "rm -rf \"${ENGRAM_DATA_DIR}\""
+else
+  echo "Left engram data intact at ${ENGRAM_DATA_DIR} (pass --purge-data to delete)."
+fi
+
+echo "Done. Source repos under your DEV_ROOT were left untouched."

scripts/verify-soul-contract.sh

@@ -0,0 +1,261 @@
+#!/usr/bin/env bash
+# verify-soul-contract.sh — the soul contract gate.
+#
+# TERMINOLOGY (canonical): the ENGRAM is the brain — the memory/knowledge-graph
+# substrate. The binary this gate exercises is the SOUL — the runtime/reasoning
+# engine compiled from dist/soul.c that serves the /api/ surface. The app
+# (neuron-ui) bundles the soul binary at resources/<platform>/neuron.
+#
+# WHY THIS EXISTS
+#   For a while the soul binary was hand-dropped, and a stale one shipped: it
+#   404'd several capability routes the app calls (knowledge-graph node
+#   update/delete, live-run narration, safety-contact, ...). This gate makes
+#   shipping a stale soul IMPOSSIBLE. It has two enforced sections:
+#     A. PRESENCE   — every route the app calls must be ANSWERED (not 404, not
+#                     the el-runtime "no handler"). This is the packaging gate:
+#                     if it fails, do not package.
+#     B. IMMUTABILITY — engram nodes/memories are immutable by design. To
+#                     "update" is to create a NEW node + a supersede EDGE back to
+#                     the original; the original is KEPT. To "delete" is to
+#                     supersede/tombstone, never hard-remove. A soul that
+#                     hard-deletes an engram node is DEFECTIVE and fails the gate.
+#
+# SAFETY
+#   Never touches the live soul (:7770), live engram (:8742), or ~/.neuron.
+#   Boots on a throwaway port (default 7799) with HOME=$(mktemp -d), a throwaway
+#   engram snapshot, a non-genesis cgi id, no ENGRAM_URL (so it uses its own
+#   in-process store, never the live server), NEURON_API_URL pointed at a dead
+#   port, and no ANTHROPIC_API_KEY (so no probe triggers a real LLM call).
+#   Connectors proxy to a HARDCODED 127.0.0.1:7771 (no env override): those
+#   sub-routes are probed with GET, which the soul maps to a read-only
+#   connectd_get, so this gate never writes to a running connectd bridge.
+#
+# USAGE
+#   scripts/verify-soul-contract.sh <path-to-soul-binary> [port]
+#   exit 0 = all required routes answered AND no destructive engram mutation;
+#   non-zero = a route is missing (presence) or a mutation route hard-deletes.
+set -uo pipefail
+
+SOUL="${1:?usage: verify-soul-contract.sh <soul-binary> [port]}"
+PORT="${2:-7799}"
+
+if [ "$PORT" = "7770" ] || [ "$PORT" = "8742" ] || [ "$PORT" = "7771" ]; then
+  echo "REFUSING: port $PORT is a live service port. Use a throwaway port." >&2
+  exit 2
+fi
+if [ ! -x "$SOUL" ]; then echo "not executable: $SOUL" >&2; exit 2; fi
+
+BASE="http://127.0.0.1:$PORT"
+THROW_HOME="$(mktemp -d "${TMPDIR:-/tmp}/soul-contract-home.XXXXXX")"
+SOUL_LOG="$(mktemp "${TMPDIR:-/tmp}/soul-contract-log.XXXXXX")"
+SOUL_PID=""
+cleanup() {
+  [ -n "$SOUL_PID" ] && kill "$SOUL_PID" 2>/dev/null
+  [ -n "$SOUL_PID" ] && { sleep 0.3; kill -9 "$SOUL_PID" 2>/dev/null; }
+  rm -rf "$THROW_HOME" "$SOUL_LOG"
+}
+trap cleanup EXIT INT TERM
+
+# =============================================================================
+# THE CONTRACT — routes the app (neuron-ui/src/main/kotlin/ai/neuron/ui/*.kt)
+# calls against the soul ($SOUL). Format: "METHOD PATH".
+#
+# EXCLUDED and why:
+#   /api/auth, /api/auth/status, /api/dispatch, /api/tasks
+#       -> served by the APP's own DispatchServer.kt (localhost:8080), not the
+#          soul. Not soul routes.
+#   /api/tags
+#       -> not handled by any soul .el (app-side/other). Pre-verified excluded.
+#   /api/neuron/, /api/neuron/node/, /api/connectors/ (bare prefixes)
+#       -> base-path string constants used to build the concrete routes below.
+#
+# KNOWN-PENDING (probed + reported, NON-blocking):
+#   POST /api/engram/import  -> the app's "Restore memory" path. No soul handler
+#       yet, and the app hides Restore from shipped builds (B3, "lands in an
+#       update"). Reported so we see it; does not block packaging.
+#
+# Connectors sub-routes are listed as GET (see SAFETY note): handle_connectors is
+# monolithic, so a GET reaching it proves the whole connectors surface without
+# writing to the live bridge. Binary-strings cross-check confirms each POST
+# sub-path literal is compiled in.
+# =============================================================================
+REQUIRED=(
+  "GET  /api/graph/nodes"
+  "GET  /api/graph/edges"
+  "POST /api/chat"
+  "GET  /api/config"
+  "POST /api/see"
+  "GET  /api/connectors"
+  "GET  /api/connectors/add"
+  "GET  /api/connectors/toggle"
+  "GET  /api/connectors/auto-approve"
+  "GET  /api/connectors/remove"
+  "GET  /api/connectors/secret"
+  "GET  /api/connectors/oauth/start"
+  "GET  /api/connectors/call"
+  "POST /api/neuron/memory"
+  "POST /api/neuron/memory/update"
+  "POST /api/neuron/memory/delete"
+  "POST /api/neuron/node/create"
+  "POST /api/neuron/node/update"
+  "POST /api/neuron/node/delete"
+  "POST /api/neuron/knowledge/capture"
+  "POST /api/neuron/knowledge/evolve"
+  "POST /api/neuron/knowledge/promote"
+  "POST /api/neuron/processes/define"
+  "GET  /api/run-progress/__contract_probe__"
+  "GET  /api/safety-contact"
+  "POST /api/safety-contact"
+  "GET  /api/sessions/__contract_probe__"
+)
+KNOWN_PENDING=(
+  "POST /api/engram/import"
+)
+
+# --- boot the soul -----------------------------------------------------------
+# Preserve the ambient environment (PATH, LD_LIBRARY_PATH, TMPDIR) so the
+# dynamically-linked soul finds its libs on any runner — using `env -i` here
+# stripped the library path on the Linux CI runner and the soul never booted.
+# Isolation is still guaranteed by UNSETTING the live-service vars (so it can
+# never reach the real engram/axon or make an LLM call) and by pointing HOME +
+# the snapshot at throwaway paths and the axon at a dead port.
+#
+# ISOLATION FIX (2026-08-03): unsetting ENGRAM_URL/SOUL_ENGRAM_URL is NOT enough.
+# The periodic engram sync (awareness.el) resolves its source as
+#   env(SOUL_ISE_URL)  ->  state(soul_engram_url)  ->  DEFAULT http://localhost:8742
+# so with those vars unset it silently pulls the LIVE engram (:8742) if that
+# server is up — the throwaway graph ballooned 56 -> 12k live nodes within
+# seconds, and the concurrent live-sync mutation both (a) broke test determinism
+# (the low-salience tombstone marker fell past the 9999 scan cap) and (b) meant
+# the "isolated" gate was reading the operator's live brain. Pin SOUL_ISE_URL to
+# the dead axon port so the sync target is unreachable: the soul stays on its own
+# in-process store, the gate is genuinely isolated, and Section B is deterministic.
+echo "== booting soul: $SOUL on port $PORT (throwaway HOME=$THROW_HOME) =="
+env \
+  -u ENGRAM_URL -u ENGRAM_API_KEY -u SOUL_ENGRAM_URL \
+  -u ANTHROPIC_API_KEY -u NEURON_LLM_API_KEY -u SOUL_IDENTITY \
+  HOME="$THROW_HOME" \
+  NEURON_PORT="$PORT" \
+  SOUL_CGI_ID="ntn-contract-$$" \
+  SOUL_ENGRAM_PATH="$THROW_HOME/throwaway-snapshot.json" \
+  NEURON_API_URL="http://127.0.0.1:9" \
+  SOUL_ISE_URL="http://127.0.0.1:9" \
+  SOUL_TICK_MS="3600000" SOUL_HEARTBEAT_MS="3600000" SOUL_REFRESH_MS="3600000" \
+  "$SOUL" >"$SOUL_LOG" 2>&1 &
+SOUL_PID=$!
+
+UP=0
+for _ in $(seq 1 60); do
+  if ! kill -0 "$SOUL_PID" 2>/dev/null; then
+    echo "!! soul exited during boot. log tail:" >&2; tail -20 "$SOUL_LOG" >&2; exit 3
+  fi
+  RSS=$(ps -o rss= -p "$SOUL_PID" 2>/dev/null | tr -d ' ')
+  if [ -n "$RSS" ] && [ "$RSS" -gt $((3*1024*1024)) ]; then
+    echo "!! soul RSS >3GB — kill -9" >&2; kill -9 "$SOUL_PID" 2>/dev/null; exit 3
+  fi
+  [ "$(curl -s -o /dev/null -w '%{http_code}' -m 2 "$BASE/health" 2>/dev/null)" = "200" ] && { UP=1; break; }
+  sleep 0.5
+done
+[ "$UP" = 1 ] || { echo "!! soul never healthy on $BASE/health" >&2; tail -20 "$SOUL_LOG" >&2; exit 3; }
+echo "== soul healthy =="; echo
+
+# --- probing helpers ---------------------------------------------------------
+# request METHOD PATH [BODY] -> prints response body (single line)
+request() {
+  curl -s -m 12 -X "$1" -H 'Content-Type: application/json' --data "${3:-{}}" "$BASE$2" 2>/dev/null | tr -d '\n'
+}
+# is_missing BODY -> 0 if the body is a "route not present" signal
+is_missing() {
+  printf '%s' "$1" | grep -qE '"error":"not found"|"code":"not_found"|no http handler registered|"code":"method_not_allowed"'
+}
+extract_id() { printf '%s' "$1" | grep -oE '"id":"[^"]+"' | head -1 | sed 's/.*"id":"//;s/"//'; }
+# BY-ID immutability verification (#199 by-id gate).
+# The prior check grepped /api/graph/nodes, i.e. engram_scan_nodes_json(9999,0):
+# a whole-graph dump. On a genesis-seeded throwaway engram that list is both
+# huge (multi-MB, full node content + embeddings) AND capped at 9999 nodes in
+# salience order. The tombstone MARKER is written at salience 0.01, so it sorts
+# dead last — and once the seeded graph approaches/exceeds the cap the marker
+# falls off the end of the list entirely (or is lost to transport truncation on
+# the ~10MB body). The normal-salience original still sorts early and survives,
+# which is why a correctly-tombstoning soul false-reported "kept but no tombstone
+# marker". Fix: verify BY ID via /api/neuron/graph?id=<id>&depth=1
+# (engram_neighbors_json, direction "both"), a compact ~900B neighborhood that is
+# independent of total graph size. The node itself proves KEPT; the incoming
+# "tombstones" edge surfaces the "tombstone:<id>" marker. Pass/fail semantics are
+# unchanged and strictly no weaker: a hard-delete leaves no by-id node (DESTROYED)
+# and a no-op delete leaves no marker (NO-OP) — both still fail. Verified: a
+# never-created id returns neither node nor marker.
+node_present() { # id -> 0 if the node still resolves by-id (KEPT), non-zero if hard-removed
+  request GET "/api/neuron/graph?id=$1&depth=1" | grep -qF "\"$1\""
+}
+
+# --- SECTION A: presence -----------------------------------------------------
+run_presence() {
+  local -n arr=$1; local fail=0
+  printf '  %-8s %-42s %s\n' "METHOD" "ROUTE" "RESULT"
+  for e in "${arr[@]}"; do
+    local m p body; m=$(awk '{print $1}' <<<"$e"); p=$(awk '{print $2}' <<<"$e")
+    body=$(request "$m" "$p")
+    if is_missing "$body"; then
+      printf '  %-8s %-42s MISSING  %s\n' "$m" "$p" "$(cut -c1-46 <<<"$body")"; fail=$((fail+1))
+    else
+      printf '  %-8s %-42s ANSWERED %s\n' "$m" "$p" "$(cut -c1-46 <<<"$body")"
+    fi
+  done
+  return $fail
+}
+
+echo "== SECTION A: PRESENCE (required, blocking) =="
+run_presence REQUIRED; A_FAIL=$?
+echo
+echo "== KNOWN-PENDING (non-blocking) =="
+run_presence KNOWN_PENDING; P_FAIL=$?
+echo
+
+# --- SECTION B: immutability (engram write routes must supersede, not destroy) --
+# For each mutation route: create a node, mutate it, then check the ORIGINAL id
+# still exists in the graph. KEPT = supersede/tombstone (correct). DESTROYED =
+# hard delete (DEFECTIVE -> fail). N/A = mutate route absent (a presence failure).
+# For "delete" mutations we additionally require a real tombstone marker
+# (label "tombstone:<id>") so a no-op delete cannot false-pass as KEPT.
+marker_present() { # id -> 0 if a "tombstone:<id>" marker is wired to the node (by-id neighborhood)
+  request GET "/api/neuron/graph?id=$1&depth=1" | grep -qF "tombstone:$1"
+}
+immut_check() { # label KIND(update|delete) CREATE_PATH MUTATE_PATH
+  local label="$1" kind="$2" create="$3" mutate="$4"
+  local cbody id mb mbody
+  cbody=$(request POST "$create" "{\"content\":\"__immut_${label}__\",\"node_type\":\"Memory\",\"label\":\"contract:immut\"}")
+  id=$(extract_id "$cbody")
+  if [ -z "$id" ]; then printf '  %-14s SKELETON-FAIL  create returned no id: %s\n' "$label" "$(cut -c1-40 <<<"$cbody")"; return 2; fi
+  mb="{\"id\":\"$id\"}"; [ "$kind" = update ] && mb="{\"id\":\"$id\",\"content\":\"__immut_${label}_v2__\"}"
+  mbody=$(request POST "$mutate" "$mb")
+  if is_missing "$mbody"; then printf '  %-14s N/A            mutate route absent (see Section A)\n' "$label"; return 0; fi
+  if ! node_present "$id"; then
+    printf '  %-14s DESTROYED      original %s hard-removed  <== DEFECTIVE\n' "$label" "$id"; return 1
+  fi
+  if [ "$kind" = delete ] && ! marker_present "$id"; then
+    printf '  %-14s NO-OP          original %s kept but no tombstone marker  <== DEFECTIVE\n' "$label" "$id"; return 1
+  fi
+  local how="supersede edge"; [ "$kind" = delete ] && how="tombstoned + hidden from default list"
+  printf '  %-14s KEPT           original %s survived (%s)\n' "$label" "$id" "$how"; return 0
+}
+
+echo "== SECTION B: IMMUTABILITY (engram nodes must be superseded, never destroyed) =="
+B_FAIL=0
+immut_check "memory-update" update /api/neuron/memory      /api/neuron/memory/update || B_FAIL=$((B_FAIL+$?))
+immut_check "memory-delete" delete /api/neuron/memory      /api/neuron/memory/delete || B_FAIL=$((B_FAIL+$?))
+immut_check "node-update"   update /api/neuron/node/create /api/neuron/node/update   || B_FAIL=$((B_FAIL+$?))
+immut_check "node-delete"   delete /api/neuron/node/create /api/neuron/node/delete   || B_FAIL=$((B_FAIL+$?))
+immut_check "memory-forget" delete /api/neuron/memory      /api/neuron/memory/forget || B_FAIL=$((B_FAIL+$?))
+echo
+
+echo "============================================================"
+RC=0
+if [ "$A_FAIL" -gt 0 ]; then echo "PRESENCE:   FAIL — $A_FAIL required route(s) unanswered. Do NOT package."; RC=1
+  else echo "PRESENCE:   PASS — all ${#REQUIRED[@]} required routes answered."; fi
+if [ "$B_FAIL" -gt 0 ]; then echo "IMMUTABILITY: FAIL — $B_FAIL engram write route(s) hard-delete. DEFECTIVE soul."; RC=1
+  else echo "IMMUTABILITY: PASS — no engram write route hard-deletes."; fi
+[ "$P_FAIL" -gt 0 ] && echo "note: $P_FAIL known-pending route(s) unanswered (expected; non-blocking)."
+echo "============================================================"
+[ "$RC" = 0 ] && echo "GATE: PASS" || echo "GATE: FAIL"
+exit $RC

sessions.el

@@ -677,6 +677,11 @@ fn handle_session_approve(session_id: String, body: String) -> String {
     // path for all sessions created through handle_chat_agentic / agentic_loop.
     let bridge_blob: String = state_get("mcp_bridge:" + session_id)
     if !str_eq(bridge_blob, "") {
+        // BUG-LEAK fix (2026-07-16): the approved tool executes below via dispatch_tool,
+        // whose path/command guards read the shared workspace-root key. Re-assert THIS
+        // session's own root first — an approval must never execute under whatever root
+        // the last unrelated request left behind.
+        state_set("agent_workspace_root", state_get("agent_workspace_root_" + session_id))
         // For "always": record tool_name in the always-allow list before resuming.
         // The tool_name is not stored in the bridge blob (only tool_use_id is).
         // Accept it from the body so the client can pass it along.
@@ -708,7 +713,13 @@ fn handle_session_approve(session_id: String, body: String) -> String {
         // For builtin tools with no client-provided content: fall back to
         // dispatch_tool so those tools still execute correctly.
         let client_content: String = json_get(body, "content")
-        let use_client_content: Bool = !str_eq(client_content, "")
+        // BUG-6 fix (2026-07-17): the naive json_get scanner matches "content" ANYWHERE
+        // in the body — including INSIDE tool_input — so every approved write_file (whose
+        // input always carries a content field) was mistaken for client-executed, never
+        // dispatched, and narrated as done: a false receipt with no file on disk. Builtin
+        // tools now ALWAYS dispatch server-side; client content is only honored for
+        // non-builtin (MCP/client-executed) tools. Stricter only.
+        let use_client_content: Bool = !str_eq(client_content, "") && !is_builtin_tool(approve_tool_name)
         let use_dispatch: Bool = is_builtin_tool(approve_tool_name) && !use_client_content
         let raw_input: String = json_get_raw(body, "tool_input")
         let eff_input: String = if str_eq(raw_input, "") { "{}" } else { raw_input }

soul.el

@@ -521,7 +521,7 @@ let axon_raw: String = env("NEURON_API_URL")
 let axon_base: String = if str_eq(axon_raw, "") { "http://localhost:7771" } else { axon_raw }
 
 let studio_dir_raw: String = env("SOUL_STUDIO_DIR")
-let studio_dir: String = if str_eq(studio_dir_raw, "") { "/Users/will/Development/neuron-technologies/products/cgi-studio/el-daemon" } else { studio_dir_raw }
+let studio_dir: String = if str_eq(studio_dir_raw, "") { env("HOME") + "/Development/neuron-technologies/products/cgi-studio/el-daemon" } else { studio_dir_raw }
 
 println("[soul] boot - cgi=" + soul_cgi_id + " port=" + int_to_str(port))
 

vendor/el-runtime/v1.0.0-20260501/RELEASE.md

@@ -0,0 +1,28 @@
+# El Compiler Release v1.0.0 — 2026-05-02
+
+## Components
+- `bootstrap.py` — El language compiler (Python, recursive descent parser, emits C)
+- `el_runtime.c` — El runtime (C, HTTP server, engram, DHARMA, LLM chain)
+- `el_runtime.h` — Runtime public API header
+
+## Changes in this release
+
+### Critical bug fixes
+- `state_set`/`state_get` are now thread-safe (pthread_mutex). Was racing across 64 worker threads.
+- `looks_like_string` threshold raised from 1,000,000 to 4GB. Unix timestamps were being dereferenced as heap pointers.
+- `fs_read` guards against negative `ftell` result (pipe/special file overflow).
+
+### Engram architecture (major)
+- Two-layer activation: `background_activation` (Layer 1, broad fan-out) + `working_memory_weight` (Layer 2, executive filter)
+- Inhibitory edges: `EngramEdge.inhibitory` flag suppresses working memory promotion without affecting background activation
+- Suppression memory: `suppression_count` — nodes activated-but-suppressed accumulate pressure toward breakthrough
+- Temporal decay: `temporal_decay_rate`, `created_at`, `last_activated_at`, `activation_count` on EngramNode
+- Per-type activation thresholds (Safety: 0.05, Canonical: 0.15, Lesson: 0.25, Note: 0.40)
+- Temporal range query: `engram_query_range(start_ms, end_ms)`
+- Layered consciousness: `EngramLayer` struct, `layer_id` on nodes and edges, `EngramStore.layers[]`
+- Layer 0 override pass: safety layer fires last and cannot be suppressed
+
+## SHA256
+bootstrap.py
+el_runtime.c
+el_runtime.h

vendor/el-runtime/v1.0.0-20260501/el_runtime.h

@@ -0,0 +1,786 @@
+/*
+ * el_runtime.h — El language C runtime header
+ *
+ * Declares all built-in functions available to compiled El programs.
+ * Include this in every generated .c file.
+ *
+ * Value model:
+ *   All El values are represented as el_val_t (= int64_t).
+ *   On 64-bit systems a pointer fits in int64_t.
+ *   String values are cast: (el_val_t)(uintptr_t)"hello"
+ *   Integer values are stored directly.
+ *   This lets arithmetic work naturally while still passing strings around.
+ *
+ * Type conventions (El -> C):
+ *   String  -> el_val_t  (holds const char* via uintptr_t cast)
+ *   Int     -> el_val_t
+ *   Bool    -> el_val_t  (0 = false, nonzero = true)
+ *   Any     -> el_val_t
+ *   Void    -> void
+ *
+ * Macros for convenience:
+ *   EL_STR(s)    cast string literal to el_val_t
+ *   EL_CSTR(v)   cast el_val_t back to const char*
+ *   EL_INT(v)    identity — el_val_t is already int64_t
+ *
+ * Link requirements:
+ *   -lcurl     — required for the HTTP client (http_get, http_post, llm_*).
+ *   -lpthread  — required for the HTTP server (one detached thread per
+ *                connection, capped at 64 concurrent).
+ *   -loqs      — optional; required only when liboqs is installed and the
+ *                pq_* / sha3_256_hex entry points are needed. Detected at
+ *                compile time via __has_include(<oqs/oqs.h>).
+ *   -lcrypto   — optional; pulled in alongside -loqs. Used for X25519 in
+ *                pq_hybrid_* and HKDF-SHA256 derivation.
+ *
+ * Canonical compile command:
+ *   cc -std=c11 -I el-compiler/runtime -lcurl -lpthread \
+ *      -o <out> <prog>.c el-compiler/runtime/el_runtime.c
+ *
+ * With liboqs (post-quantum stack):
+ *   cc -std=c11 -I el-compiler/runtime -lcurl -lpthread -loqs -lcrypto \
+ *      -o <out> <prog>.c el-compiler/runtime/el_runtime.c
+ */
+
+#pragma once
+
+#include <stdint.h>
+#include <stdlib.h>
+
+typedef int64_t el_val_t;
+
+#define EL_STR(s)  ((el_val_t)(uintptr_t)(s))
+#define EL_CSTR(v) ((const char*)(uintptr_t)(v))
+#define EL_INT(v)  (v)
+#define EL_NULL    ((el_val_t)0)
+
+/* Float values share the el_val_t (int64) slot via a bit-cast.
+ * The codegen emits Float literals as `el_from_float(<dbl>)` so the
+ * underlying bits represent the IEEE 754 double. Float-aware builtins
+ * (math, format, json) round-trip via these helpers. */
+static inline double el_to_float(el_val_t v) {
+    union { int64_t i; double f; } u;
+    u.i = (int64_t)v;
+    return u.f;
+}
+
+static inline el_val_t el_from_float(double f) {
+    union { double f; int64_t i; } u;
+    u.f = f;
+    return (el_val_t)u.i;
+}
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* ── I/O ──────────────────────────────────────────────────────────────────── */
+
+void      println(el_val_t s);
+void      print(el_val_t s);
+el_val_t  readline(void);
+
+/* ── String builtins ─────────────────────────────────────────────────────── */
+
+el_val_t  el_str_concat(el_val_t a, el_val_t b);
+el_val_t  str_eq(el_val_t a, el_val_t b);
+el_val_t  str_starts_with(el_val_t s, el_val_t prefix);
+el_val_t  str_ends_with(el_val_t s, el_val_t suffix);
+el_val_t  str_len(el_val_t s);
+el_val_t  str_concat(el_val_t a, el_val_t b);
+el_val_t  int_to_str(el_val_t n);
+el_val_t  str_to_int(el_val_t s);
+el_val_t  str_slice(el_val_t s, el_val_t start, el_val_t end);
+el_val_t  str_contains(el_val_t s, el_val_t sub);
+el_val_t  str_replace(el_val_t s, el_val_t from, el_val_t to);
+el_val_t  str_to_upper(el_val_t s);
+el_val_t  str_to_lower(el_val_t s);
+el_val_t  str_trim(el_val_t s);
+
+/* ── Math ────────────────────────────────────────────────────────────────── */
+
+el_val_t  el_abs(el_val_t n);
+el_val_t  el_max(el_val_t a, el_val_t b);
+el_val_t  el_min(el_val_t a, el_val_t b);
+
+/* ── Refcount (ARC) ──────────────────────────────────────────────────────────
+ * Lists and Maps carry a refcount. Strings and ints do not — el_retain and
+ * el_release are safe no-ops on non-refcounted values (they sniff a magic
+ * header at offset 0 and only act if the magic matches).
+ *
+ * Codegen emits these at let-binding shadowing, function entry (params), and
+ * function exit (locals other than the returned value). The refcount lets
+ * el_list_append and el_map_set mutate in place when uniquely owned (cheap)
+ * and copy-on-write when shared (preserves persistent semantics across
+ * accumulator patterns in the compiler itself).                              */
+
+void      el_retain(el_val_t v);
+void      el_release(el_val_t v);
+
+/* ── Arena scoping ────────────────────────────────────────────────────────────
+ * el_arena_push() activates the string arena (if not already active) and
+ * returns a mark; el_arena_pop(mark) frees all strings allocated since that
+ * mark. Used by codegen for per-function/statement scoping and by long-running
+ * EL loops (e.g. the soul daemon's awareness tick) to reclaim per-iteration
+ * allocations. */
+el_val_t  el_arena_push(void);
+el_val_t  el_arena_pop(el_val_t mark);
+
+/* ── List ────────────────────────────────────────────────────────────────── */
+
+el_val_t  el_list_new(el_val_t count, ...);
+el_val_t  el_list_len(el_val_t list);
+el_val_t  el_list_get(el_val_t list, el_val_t index);
+el_val_t  el_list_append(el_val_t list, el_val_t elem);
+el_val_t  el_list_empty(void);
+el_val_t  el_list_clone(el_val_t list);
+
+/* ── Map ─────────────────────────────────────────────────────────────────── */
+
+el_val_t  el_map_new(el_val_t pair_count, ...);
+el_val_t  el_get_field(el_val_t map, el_val_t key);
+el_val_t  el_map_get(el_val_t map, el_val_t key);
+el_val_t  el_map_set(el_val_t map, el_val_t key, el_val_t value);
+
+/* ── HTTP ─────────────────────────────────────────────────────────────────── */
+
+el_val_t  http_get(el_val_t url);
+el_val_t  http_post(el_val_t url, el_val_t body);
+el_val_t  http_post_json(el_val_t url, el_val_t json_body);
+el_val_t  http_get_with_headers(el_val_t url, el_val_t headers_map);
+el_val_t  http_post_with_headers(el_val_t url, el_val_t body, el_val_t headers_map);
+el_val_t  http_post_form_auth(el_val_t url, el_val_t form_body, el_val_t auth_header);
+el_val_t  http_delete(el_val_t url);
+el_val_t  http_delete_json(el_val_t url, el_val_t json_body);
+void      http_serve(el_val_t port, el_val_t handler);
+void      http_set_handler(el_val_t name);
+
+/* HTTP server v2 ─────────────────────────────────────────────────────────────
+ * Same dispatch model as http_serve, but the handler signature is widened:
+ *
+ *     el_val_t handler(method, path, headers_map, body)
+ *
+ * `headers_map` is an ElMap from lowercased header name → header value (both
+ * Strings). Repeated headers are joined with ", " per RFC 7230.
+ *
+ * Response value: the handler may return either
+ *   (a) a plain body string — same auto-content-type / 200-OK behaviour as
+ *       http_serve (3-arg) — or
+ *   (b) a response envelope built with `http_response(status, headers_json,
+ *       body)`. The runtime detects the envelope discriminator
+ *       `"el_http_response":1` at the start of the returned string and
+ *       unpacks status / headers / body before sending.
+ *
+ * The 3-arg http_serve(port, handler) remains supported unchanged for
+ * existing handlers (e.g. products/web/server.el): it dispatches with
+ * (method, path, body), hardcodes 200 OK, and auto-detects content type. */
+void      http_serve_v2(el_val_t port, el_val_t handler);
+void      http_set_handler_v2(el_val_t name);
+
+/* Non-blocking variant of http_serve: runs the accept loop in a background
+ * pthread and returns immediately so the caller can continue (used by the
+ * soul daemon to run awareness_run() after starting its HTTP API). */
+void      http_serve_async(el_val_t port, el_val_t handler);
+
+/* Build an HTTP response envelope. `headers_json` should be a JSON object
+ * literal like `{"WWW-Authenticate":"Basic"}` (or "" / "{}" for none). The
+ * returned string carries the discriminator `{"el_http_response":1,...}`
+ * which the runtime's send-path detects and unpacks. Detection happens
+ * uniformly inside http_send_response, so a 3-arg handler may also return
+ * an envelope. The 3-arg variant remains documented as a fixed 200-OK
+ * auto-content-type contract for legacy handlers that return plain bodies. */
+el_val_t  http_response(el_val_t status, el_val_t headers_json, el_val_t body);
+
+/* HTTP timeout — every libcurl request honors EL_HTTP_TIMEOUT_MS (default
+ * 60000ms). Read lazily on first use, so setting the env var any time before
+ * the first http_* call is sufficient.                                    */
+
+/* Streaming variants — write the response body straight to a file via
+ * libcurl's CURLOPT_WRITEFUNCTION = fwrite. These bypass the el_val_t string
+ * wrapper entirely, so binary payloads (audio/mpeg, image/png, etc.) survive
+ * embedded NUL bytes that would truncate a strlen()-based code path.
+ *
+ * Both honor EL_HTTP_TIMEOUT_MS, follow redirects, and accept the same
+ * `headers_map` shape as http_post_with_headers (ElMap of String→String).
+ *
+ * Return value: 1 on success (file fully written), 0 on any failure
+ * (network, file open, partial write). On failure the output file is removed
+ * so callers cannot mistake a partially-written file for a valid one. */
+el_val_t  http_post_to_file(el_val_t url, el_val_t body, el_val_t headers_map, el_val_t output_path);
+el_val_t  http_get_to_file(el_val_t url, el_val_t headers_map, el_val_t output_path);
+
+/* ── URL encoding ────────────────────────────────────────────────────────── */
+
+el_val_t  url_encode(el_val_t s);   /* RFC 3986 unreserved set */
+el_val_t  url_decode(el_val_t s);   /* '+' → space, %XX → byte  */
+
+/* ── HTML allowlist sanitizer ────────────────────────────────────────────────
+ * el_html_sanitize(input_html, allowlist_json) — strict allowlist HTML
+ * cleaner. State-machine parser; tag/attribute names compared case-
+ * insensitively against the allowlist; `<a href>` / `<… src>` URL schemes
+ * validated (http, https, mailto, fragment-only, or relative); whole-
+ * subtree drop for script / style / iframe / object / embed / form; HTML-
+ * escapes free text outside dropped subtrees.
+ *
+ * The allowlist is JSON of the form
+ *     {"p":[],"a":["href","title"],"strong":[],...}
+ * where each value is the array of attribute names allowed for that tag. */
+el_val_t  el_html_sanitize(el_val_t input_html, el_val_t allowlist_json);
+
+/* ── Filesystem ──────────────────────────────────────────────────────────── */
+
+el_val_t  fs_read(el_val_t path);
+el_val_t  fs_write(el_val_t path, el_val_t content);
+el_val_t  fs_list(el_val_t path);
+el_val_t  fs_exists(el_val_t path);
+el_val_t  fs_mkdir(el_val_t path);   /* mkdir -p, mode 0755                */
+
+/* Length-explicit binary write. `length` is an Int (el_val_t holding the
+ * byte count). The caller knows the length from context — typically because
+ * `bytes` came from base64_decode (which produces a magic-tagged binary
+ * buffer with embedded NULs possible) and the caller already tracks the
+ * decoded length, OR because the bytes came from a fixed-size source
+ * (sha256_bytes = 32, hmac_sha256_bytes = 32). Bypasses strlen entirely.
+ *
+ * Returns 1 on success, 0 on failure (invalid path, can't open, partial
+ * write, negative length). On partial-write failure, the file is removed
+ * so callers cannot read back a truncated artefact. */
+el_val_t  fs_write_bytes(el_val_t path, el_val_t bytes, el_val_t length);
+
+/* ── JSON ────────────────────────────────────────────────────────────────── */
+
+el_val_t  json_get(el_val_t json, el_val_t key);
+el_val_t  json_parse(el_val_t s);
+el_val_t  json_stringify(el_val_t v);
+el_val_t  json_get_string(el_val_t json_str, el_val_t key);
+el_val_t  json_get_int(el_val_t json_str, el_val_t key);
+el_val_t  json_get_float(el_val_t json_str, el_val_t key);
+el_val_t  json_get_bool(el_val_t json_str, el_val_t key);
+el_val_t  json_get_raw(el_val_t json_str, el_val_t key);
+el_val_t  json_set(el_val_t json_str, el_val_t key, el_val_t value);
+el_val_t  json_array_len(el_val_t json_str);
+el_val_t  json_array_get(el_val_t json_str, el_val_t index);
+el_val_t  json_array_get_string(el_val_t json_str, el_val_t index);
+
+/* ── Time ────────────────────────────────────────────────────────────────── */
+
+el_val_t  time_now(void);
+el_val_t  time_now_utc(void);
+el_val_t  sleep_secs(el_val_t secs);
+el_val_t  sleep_ms(el_val_t ms);
+el_val_t  time_format(el_val_t ts, el_val_t fmt);
+el_val_t  time_to_parts(el_val_t ts);
+el_val_t  time_from_parts(el_val_t secs, el_val_t ns, el_val_t tz);
+el_val_t  time_add(el_val_t ts, el_val_t n, el_val_t unit);
+el_val_t  time_diff(el_val_t ts1, el_val_t ts2, el_val_t unit);
+
+/* ── Instant + Duration: first-class temporal types ──────────────────────────
+ * Both types share the el_val_t (int64) slot. Instants are nanoseconds
+ * since the Unix epoch; Durations are signed nanoseconds. Type discipline
+ * is enforced at codegen-time: BinOps on names registered as Instant or
+ * Duration route through the typed wrappers below; mismatches like
+ * Instant+Instant become #error at the C compiler.
+ *
+ * Postfix literals — `30.seconds`, `1.hour`, `500.millis`, `30.nanos` — are
+ * recognised by the parser as DurationLit AST nodes and lowered to literal
+ * int64 nanoseconds at codegen time. The runtime never sees the units. */
+
+el_val_t  el_now_instant(void);
+el_val_t  now(void);
+el_val_t  unix_seconds(el_val_t n);
+el_val_t  unix_millis(el_val_t n);
+el_val_t  instant_from_iso8601(el_val_t s);
+
+el_val_t  el_duration_from_nanos(el_val_t ns);
+el_val_t  duration_seconds(el_val_t n);
+el_val_t  duration_millis(el_val_t n);
+el_val_t  duration_nanos(el_val_t n);
+
+el_val_t  el_instant_add_dur(el_val_t inst, el_val_t dur);
+el_val_t  el_instant_sub_dur(el_val_t inst, el_val_t dur);
+el_val_t  el_instant_diff(el_val_t a, el_val_t b);
+el_val_t  el_duration_add(el_val_t a, el_val_t b);
+el_val_t  el_duration_sub(el_val_t a, el_val_t b);
+el_val_t  el_duration_scale(el_val_t dur, el_val_t scalar);
+el_val_t  el_duration_div(el_val_t dur, el_val_t scalar);
+
+el_val_t  el_instant_lt(el_val_t a, el_val_t b);
+el_val_t  el_instant_le(el_val_t a, el_val_t b);
+el_val_t  el_instant_gt(el_val_t a, el_val_t b);
+el_val_t  el_instant_ge(el_val_t a, el_val_t b);
+el_val_t  el_instant_eq(el_val_t a, el_val_t b);
+el_val_t  el_instant_ne(el_val_t a, el_val_t b);
+el_val_t  el_duration_lt(el_val_t a, el_val_t b);
+el_val_t  el_duration_le(el_val_t a, el_val_t b);
+el_val_t  el_duration_gt(el_val_t a, el_val_t b);
+el_val_t  el_duration_ge(el_val_t a, el_val_t b);
+el_val_t  el_duration_eq(el_val_t a, el_val_t b);
+el_val_t  el_duration_ne(el_val_t a, el_val_t b);
+
+el_val_t  instant_to_unix_seconds(el_val_t i);
+el_val_t  instant_to_unix_millis(el_val_t i);
+el_val_t  instant_to_iso8601(el_val_t i);
+el_val_t  duration_to_seconds(el_val_t d);
+el_val_t  duration_to_millis(el_val_t d);
+el_val_t  duration_to_nanos(el_val_t d);
+
+el_val_t  el_sleep_duration(el_val_t dur);
+el_val_t  unix_timestamp(void);
+
+el_val_t  ttl_cache_set(el_val_t key, el_val_t value);
+el_val_t  ttl_cache_get(el_val_t key, el_val_t max_age);
+el_val_t  ttl_cache_age(el_val_t key);
+
+/* ── Calendar + CalendarTime + Rhythm + LocalDate/Time/DateTime ─────────────
+ * Phase 1.5 of the time system. Calendar is pluggable: EarthCalendar (IANA
+ * zones, Gregorian, DST) is the user-facing default; MarsCalendar,
+ * CycleCalendar(period), NoCycleCalendar, RelativeCalendar handle non-Earth
+ * domains.
+ *
+ * A Calendar interprets an Instant under a particular cycle convention and
+ * produces a CalendarTime. CalendarTime carries the underlying Instant and
+ * a back-pointer to its Calendar; arithmetic and formatting consult the
+ * Calendar to convert ns since epoch into year/month/day/hour/minute/second
+ * (or sol/phase, or cycle/phase, depending on kind).
+ *
+ * Storage convention: Calendar / CalendarTime / Rhythm / LocalDate /
+ * LocalDateTime are heap-allocated structs whose pointers are cast into
+ * el_val_t. A 24-bit magic header at offset 0 lets the runtime identify
+ * the kind safely. LocalTime is small enough to live in the int64 slot
+ * directly (nanos since midnight, signed).                                  */
+
+/* Zone — opaque IANA zone or fixed offset, used by EarthCalendar.
+ * `zone_id` is either an IANA name ("America/New_York", "UTC") or a fixed
+ * offset string ("+05:30", "-08:00"). The runtime resolves it via tzset()
+ * on first use of the owning EarthCalendar.                                  */
+el_val_t  zone(el_val_t id);
+el_val_t  zone_utc(void);
+el_val_t  zone_local(void);
+el_val_t  zone_offset(el_val_t hours, el_val_t minutes);
+
+/* Calendar constructors. Each returns an el_val_t pointer to a heap-
+ * allocated, magic-tagged Calendar struct. Calendars are interned by
+ * (kind, zone_id, period_ns, epoch_ns) so identical constructors return
+ * the same pointer — equality is reference equality.                        */
+el_val_t  earth_calendar(el_val_t z);
+el_val_t  earth_calendar_default(void);
+el_val_t  mars_calendar(void);
+el_val_t  cycle_calendar(el_val_t period_dur);
+el_val_t  no_cycle_calendar(void);
+el_val_t  relative_calendar(el_val_t epoch_inst);
+
+/* CalendarTime constructors and methods. Returns a heap-allocated struct
+ * whose pointer fits in el_val_t. */
+el_val_t  now_in(el_val_t cal);
+el_val_t  in_calendar(el_val_t inst, el_val_t cal);
+el_val_t  cal_format(el_val_t ct, el_val_t pattern);
+el_val_t  cal_to_instant(el_val_t ct);
+el_val_t  cal_cycle_phase(el_val_t ct);
+el_val_t  cal_in(el_val_t ct, el_val_t cal);
+
+/* LocalDate / LocalTime / LocalDateTime — calendar-agnostic value types.
+ * LocalTime carries nanoseconds since midnight as a signed int64 directly
+ * in the el_val_t slot (no allocation). LocalDate / LocalDateTime are
+ * heap-allocated structs with magic headers. */
+el_val_t  local_date(el_val_t y, el_val_t m, el_val_t d);
+el_val_t  local_time(el_val_t h, el_val_t m, el_val_t s, el_val_t ns);
+el_val_t  local_datetime(el_val_t date, el_val_t time);
+el_val_t  zoned(el_val_t date, el_val_t time, el_val_t cal);
+
+el_val_t  local_date_year(el_val_t ld);
+el_val_t  local_date_month(el_val_t ld);
+el_val_t  local_date_day(el_val_t ld);
+el_val_t  local_time_hour(el_val_t lt);
+el_val_t  local_time_minute(el_val_t lt);
+el_val_t  local_time_second(el_val_t lt);
+el_val_t  local_time_nanos(el_val_t lt);
+
+el_val_t  el_local_date_add_dur(el_val_t ld, el_val_t dur);
+el_val_t  el_local_time_add_dur(el_val_t lt, el_val_t dur);
+el_val_t  el_local_date_lt(el_val_t a, el_val_t b);
+el_val_t  el_local_date_eq(el_val_t a, el_val_t b);
+
+/* Rhythm — pluggable recurrence AST. Returns a heap-allocated struct
+ * pointer in el_val_t; rhythms are immutable so callers may share them. */
+el_val_t  rhythm_cycle_start(void);
+el_val_t  rhythm_cycle_phase(el_val_t phase);
+el_val_t  rhythm_duration(el_val_t d);
+el_val_t  rhythm_session_start(void);
+el_val_t  rhythm_event(el_val_t name);
+el_val_t  rhythm_and(el_val_t a, el_val_t b);
+el_val_t  rhythm_or(el_val_t a, el_val_t b);
+el_val_t  rhythm_weekday(el_val_t day);
+el_val_t  rhythm_weekly_at(el_val_t day, el_val_t hour, el_val_t minute);
+el_val_t  rhythm_next_after(el_val_t r, el_val_t after, el_val_t cal);
+el_val_t  rhythm_matches(el_val_t r, el_val_t ct);
+
+/* ── UUID ────────────────────────────────────────────────────────────────── */
+
+el_val_t  uuid_new(void);
+el_val_t  uuid_v4(void);
+
+/* ── Environment ─────────────────────────────────────────────────────────── */
+
+el_val_t  env(el_val_t key);
+
+/* ── In-process state K/V ────────────────────────────────────────────────── */
+
+el_val_t  state_set(el_val_t key, el_val_t value);
+el_val_t  state_get(el_val_t key);
+el_val_t  state_del(el_val_t key);
+el_val_t  state_keys(void);
+
+/* ── Float formatting ────────────────────────────────────────────────────── */
+
+el_val_t  float_to_str(el_val_t f);
+el_val_t  int_to_float(el_val_t n);
+el_val_t  float_to_int(el_val_t f);
+el_val_t  format_float(el_val_t f, el_val_t decimals);
+el_val_t  decimal_round(el_val_t f, el_val_t decimals);
+el_val_t  str_to_float(el_val_t s);
+
+/* ── Math (Float-aware) ──────────────────────────────────────────────────── */
+
+el_val_t  math_sqrt(el_val_t f);
+el_val_t  math_log(el_val_t f);
+el_val_t  math_ln(el_val_t f);
+el_val_t  math_sin(el_val_t f);
+el_val_t  math_cos(el_val_t f);
+el_val_t  math_pi(void);
+
+/* ── String additions ────────────────────────────────────────────────────── */
+
+el_val_t  str_index_of(el_val_t s, el_val_t sub);
+el_val_t  str_split(el_val_t s, el_val_t sep);
+el_val_t  str_char_at(el_val_t s, el_val_t i);
+el_val_t  str_char_code(el_val_t s, el_val_t i);
+el_val_t  str_pad_left(el_val_t s, el_val_t width, el_val_t pad);
+el_val_t  str_pad_right(el_val_t s, el_val_t width, el_val_t pad);
+el_val_t  str_format(el_val_t fmt, el_val_t data);
+el_val_t  str_lower(el_val_t s);
+el_val_t  str_upper(el_val_t s);
+
+/* ── Text-processing primitives (Phase 1: byte/codepoint, ASCII char classes)
+ * Phase 2 (filed): Unicode-grapheme awareness, NFC/NFD normalization, regex.
+ * is_* predicates: empty input returns false; multi-char requires ALL bytes
+ * to match. ASCII ranges only in Phase 1. */
+
+/* Counting */
+el_val_t  str_count(el_val_t s, el_val_t sub);              /* non-overlapping */
+el_val_t  str_count_chars(el_val_t s);                      /* codepoint count */
+el_val_t  str_count_bytes(el_val_t s);                      /* alias of str_len */
+el_val_t  str_count_lines(el_val_t s);
+el_val_t  str_count_words(el_val_t s);
+el_val_t  str_count_letters(el_val_t s);                    /* ASCII [A-Za-z] */
+el_val_t  str_count_digits(el_val_t s);                     /* ASCII [0-9] */
+
+/* Find / position */
+el_val_t  str_index_of_all(el_val_t s, el_val_t sub);       /* [Int] of byte offsets */
+el_val_t  str_last_index_of(el_val_t s, el_val_t sub);
+el_val_t  str_find_chars(el_val_t s, el_val_t any_of);      /* first idx of any ch */
+
+/* Transform */
+el_val_t  str_repeat(el_val_t s, el_val_t n);
+el_val_t  str_reverse(el_val_t s);                          /* by codepoint */
+el_val_t  str_strip_prefix(el_val_t s, el_val_t prefix);
+el_val_t  str_strip_suffix(el_val_t s, el_val_t suffix);
+el_val_t  str_strip_chars(el_val_t s, el_val_t chars);
+el_val_t  str_lstrip(el_val_t s);
+el_val_t  str_rstrip(el_val_t s);
+
+/* Char classification (Bool) */
+el_val_t  is_letter(el_val_t s);
+el_val_t  is_digit(el_val_t s);
+el_val_t  is_alphanumeric(el_val_t s);
+el_val_t  is_whitespace(el_val_t s);
+el_val_t  is_punctuation(el_val_t s);
+el_val_t  is_uppercase(el_val_t s);
+el_val_t  is_lowercase(el_val_t s);
+
+/* Split / join */
+el_val_t  str_split_lines(el_val_t s);
+el_val_t  str_split_chars(el_val_t s);                      /* alias of native_string_chars */
+el_val_t  str_split_n(el_val_t s, el_val_t sep, el_val_t n);
+el_val_t  str_join(el_val_t list, el_val_t sep);            /* alias of list_join */
+
+/* ── List additions ──────────────────────────────────────────────────────── */
+
+el_val_t  list_push(el_val_t list, el_val_t elem);
+el_val_t  list_push_front(el_val_t list, el_val_t elem);
+el_val_t  list_join(el_val_t list, el_val_t sep);
+el_val_t  list_range(el_val_t start, el_val_t end);
+
+/* ── Bool helpers ────────────────────────────────────────────────────────── */
+
+el_val_t  bool_to_str(el_val_t b);
+
+/* ── Numeric parsing ─────────────────────────────────────────────────────── */
+
+el_val_t  parse_int(el_val_t s, el_val_t default_val);
+
+/* ── Process ─────────────────────────────────────────────────────────────── */
+
+void      exit_program(el_val_t code);
+el_val_t  getpid_now(void);
+
+/* ── CGI identity ─────────────────────────────────────────────────────────────
+ * Called at the start of main() in CGI programs (those with a `cgi {}` block).
+ * Records the program's DHARMA identity before any other code executes.      */
+
+void      el_cgi_init(el_val_t name, el_val_t dharma_id, el_val_t principal,
+                      el_val_t network, el_val_t engram);
+
+/* ── DHARMA network builtins ─────────────────────────────────────────────────
+ * Available to CGI programs (declared with a `cgi {}` block).
+ *
+ * Peers are addressed by `dharma_id` of the form
+ *     "<registry-id>@<transport-url>"   e.g. "ntn-genesis@http://localhost:7770"
+ * If the @<url> portion is omitted, transport defaults to
+ * "http://localhost:7770" (the local CGI daemon assumption).
+ *
+ * Wire protocol (all peers expose):
+ *   POST <url>/dharma/recv      { channel, from, content } → response body
+ *   POST <url>/dharma/event     { type, payload, source, timestamp }
+ *   POST <url>/api/activate     { query }                 → list of nodes
+ *
+ * Hosting application's responsibility: an El program with a `cgi {}` block
+ * runs http_serve() with its own request handler; that handler should route
+ * "/dharma/event" requests by calling el_runtime_dharma_event_arrive() so
+ * incoming events feed dharma_field() queues. The runtime itself does not
+ * intercept any /dharma path.                                                */
+
+el_val_t  dharma_connect(el_val_t cgi_id);
+el_val_t  dharma_send(el_val_t channel, el_val_t content);
+el_val_t  dharma_activate(el_val_t query);
+void      dharma_emit(el_val_t event_type, el_val_t payload);
+el_val_t  dharma_field(el_val_t event_type);
+void      dharma_strengthen(el_val_t cgi_id, el_val_t weight);
+el_val_t  dharma_relationship(el_val_t cgi_id);
+el_val_t  dharma_peers(void);
+
+/* Public C API: called by an El program's HTTP handler when a /dharma/event
+ * request arrives. Pushes onto the per-event-type queue and signals any
+ * pending dharma_field() blockers. All three arguments must be NUL-terminated
+ * C strings (or NULL — then treated as empty).                               */
+void      el_runtime_dharma_event_arrive(const char* event_type,
+                                         const char* payload,
+                                         const char* source);
+
+/* ── Engram local graph primitives ───────────────────────────────────────────
+ * Operate on the CGI's local Engram knowledge graph.
+ * `engram_activate` queries the local graph only; `dharma_activate` is
+ * network-wide across all connected CGI graphs.                              */
+
+el_val_t  engram_node(el_val_t content, el_val_t node_type, el_val_t salience);
+el_val_t  engram_node_full(el_val_t content, el_val_t node_type, el_val_t label,
+                           el_val_t salience, el_val_t importance, el_val_t confidence,
+                           el_val_t tier, el_val_t tags);
+/* Layered consciousness — see el_runtime.c for the layered architecture
+ * design notes (search "Layered consciousness architecture"). The five
+ * canonical layers (safety / core-identity / domain-knowledge / imprint /
+ * suit) are seeded automatically; engram_add_layer extends the registry
+ * with imprint or suit overlays at runtime. Nodes default to layer 1
+ * (core-identity) when created via engram_node / engram_node_full. */
+el_val_t  engram_node_layered(el_val_t content, el_val_t node_type, el_val_t label,
+                              el_val_t salience, el_val_t certainty, el_val_t confidence,
+                              el_val_t status, el_val_t tags, el_val_t layer_id);
+el_val_t  engram_add_layer(el_val_t name, el_val_t priority, el_val_t suppressible,
+                           el_val_t transparent, el_val_t injectable);
+el_val_t  engram_remove_layer(el_val_t layer_id);
+el_val_t  engram_list_layers(void);
+el_val_t  engram_get_node(el_val_t id);
+void      engram_strengthen(el_val_t node_id);
+void      engram_forget(el_val_t node_id);
+el_val_t  engram_prune_telemetry(el_val_t older_than_ms);
+el_val_t  engram_node_count(void);
+el_val_t  engram_search(el_val_t query, el_val_t limit);
+el_val_t  engram_scan_nodes(el_val_t limit, el_val_t offset);
+void      engram_connect(el_val_t from_id, el_val_t to_id, el_val_t weight, el_val_t relation);
+el_val_t  engram_edge_between(el_val_t from_id, el_val_t to_id);
+el_val_t  engram_neighbors(el_val_t node_id);
+el_val_t  engram_neighbors_filtered(el_val_t node_id, el_val_t max_depth, el_val_t direction);
+el_val_t  engram_edge_count(void);
+/* Three-pass activation: background fan-out → working-memory promotion →
+ * Layer 0 override. See "Three-pass activation" in el_runtime.c. */
+el_val_t  engram_activate(el_val_t query, el_val_t depth);
+el_val_t  engram_save(el_val_t path);
+el_val_t  engram_load(el_val_t path);
+
+/* JSON-string accessors — return pre-serialized JSON so HTTP handlers
+ * can pass results straight through without round-tripping ElList/ElMap
+ * through json_stringify. */
+el_val_t  engram_get_node_json(el_val_t id);
+el_val_t  engram_get_node_by_label(el_val_t label);
+el_val_t  engram_search_json(el_val_t query, el_val_t limit);
+el_val_t  engram_scan_nodes_json(el_val_t limit, el_val_t offset);
+el_val_t  engram_scan_nodes_by_type_json(el_val_t node_type, el_val_t limit, el_val_t offset);
+el_val_t  engram_neighbors_json(el_val_t node_id, el_val_t max_depth, el_val_t direction);
+el_val_t  engram_activate_json(el_val_t query, el_val_t depth);
+el_val_t  engram_stats_json(void);
+el_val_t  engram_act_stats_json(void);
+el_val_t  engram_cosine_sim(el_val_t id_a, el_val_t id_b);
+/* Document frequency of a term across node labels — term-specificity signal
+ * for curiosity seed selection. (2026-08-03 self-review.) */
+el_val_t  engram_label_df(el_val_t term);
+el_val_t  engram_embed_backfill(el_val_t count);
+el_val_t  engram_list_layers_json(void);
+/* Working memory introspection — count, mean weight, and top-N snapshot.
+ * Ported from el-compiler/runtime on 2026-06-30 self-review. */
+el_val_t  engram_wm_count(void);
+el_val_t  engram_wm_avg_weight(void);
+el_val_t  engram_wm_top_json(el_val_t n);
+/* Merge-load: add nodes/edges from a snapshot without resetting the store. */
+el_val_t  engram_load_merge(el_val_t path);
+/* engram_compile_layered_json — produce a prompt-ready text block split
+ * into "[LAYER 0 — STRUCTURAL]" (non-suppressible layers, sacred fire)
+ * and "[ENGRAM CONTEXT]" (standard suppressible layers). Returns "" if
+ * no nodes promoted to working memory. */
+el_val_t  engram_compile_layered_json(el_val_t intent, el_val_t depth);
+
+/* ── LLM (Anthropic API client) ─────────────────────────────────────────────
+ * All functions call https://api.anthropic.com/v1/messages with the API key
+ * from env ANTHROPIC_API_KEY. Default model when empty: claude-sonnet-4-5. */
+
+el_val_t  llm_call(el_val_t model, el_val_t prompt);
+el_val_t  llm_call_system(el_val_t model, el_val_t system_prompt, el_val_t user_prompt);
+el_val_t  llm_call_agentic(el_val_t model, el_val_t system, el_val_t user, el_val_t tools);
+el_val_t  llm_vision(el_val_t model, el_val_t system, el_val_t prompt, el_val_t image_url_or_b64);
+el_val_t  llm_models(void);
+
+/* Register a tool handler by name. The handler is looked up via dlsym
+ * (mirroring http_set_handler), so any El `fn <name>(input)` compiles to
+ * a global C symbol that this function can locate at runtime.
+ * Handler signature: `el_val_t handler(el_val_t input_json)` — receives
+ * the tool input as a JSON-string el_val_t and returns a JSON-string
+ * el_val_t result. Used by llm_call_agentic.                                 */
+void      llm_register_tool(el_val_t name, el_val_t handler_fn_name);
+
+/* ── args() ─────────────────────────────────────────────────────────────────
+ * Provides access to command-line arguments passed to the program.
+ * Populated by el_runtime_init_args() before main() runs.           */
+
+el_val_t  args(void);
+void      el_runtime_init_args(int argc, char** argv);
+
+/* ── Crypto primitives ─────────────────────────────────────────────────────
+ * SHA-256, HMAC-SHA-256, and base64 (standard + URL-safe).
+ * Self-contained — no OpenSSL/libcrypto dependency. The implementations are
+ * adapted from public-domain reference code (Brad Conte / RFC 4648).
+ *
+ * Bytes-returning variants (sha256_bytes, hmac_sha256_bytes) return a string
+ * value whose contents are raw binary; callers usually feed these into
+ * base64_encode. Note that el_val_t strings are NUL-terminated by convention,
+ * so the binary payload may contain embedded NULs — pass it directly into
+ * base64_encode (which uses an explicit length) rather than treating it as
+ * a printable C string.
+ *
+ * The "base64" variants emit/accept RFC 4648 standard alphabet with padding.
+ * The "base64url" variants use URL-safe alphabet (`-`/`_`) with no padding,
+ * as used in JWTs.                                                           */
+
+el_val_t  sha256_hex(el_val_t input);
+el_val_t  sha256_bytes(el_val_t input);
+el_val_t  hmac_sha256_hex(el_val_t key, el_val_t message);
+el_val_t  hmac_sha256_bytes(el_val_t key, el_val_t message);
+el_val_t  base64_encode(el_val_t input);
+el_val_t  base64_decode(el_val_t input);
+el_val_t  base64url_encode(el_val_t input);
+el_val_t  base64url_decode(el_val_t input);
+
+/* Length-aware variants (internal — exposed for the rare caller that already
+ * has a known-length binary buffer and doesn't want to round-trip through
+ * a NUL-terminated el_val_t string). Sha256_bytes and hmac_sha256_bytes feed
+ * these implicitly. */
+el_val_t  el_sha256_bytes_n(const unsigned char* data, size_t len);
+el_val_t  el_base64_encode_n(const unsigned char* data, size_t len, int url_safe);
+
+/* ── Post-quantum primitives (liboqs-backed) ────────────────────────────────
+ * All inputs/outputs hex-encoded. Algorithm choices:
+ *   Signature: CRYSTALS-Dilithium-3   (NIST level 3, balanced)
+ *   KEM:       CRYSTALS-Kyber-768     (NIST level 3)
+ *   Hash:      SHA3-256 (Keccak)      (PQ-aware protocols favour SHA3 over SHA2)
+ *
+ * If liboqs is not linked (detected via __has_include(<oqs/oqs.h>) at compile
+ * time), the pq_* entry points return a JSON-shaped error string so callers
+ * fail loudly rather than silently fall back to classical schemes:
+ *   {"error":"liboqs not linked, post-quantum primitives unavailable"}
+ *
+ * The hybrid handshake pairs X25519 with Kyber-768 per NIST PQ guidance and
+ * CNSA 2.0. Combined shared secret is HKDF-SHA256(x25519_ss || kyber_ss).
+ * Even if Kyber falls, X25519 holds; if X25519 falls under quantum attack,
+ * Kyber holds. SHA3-256 also remains usable independent of liboqs (the
+ * Keccak permutation is PQ-OK as a primitive). */
+
+el_val_t  pq_keygen_signature(void);
+el_val_t  pq_sign(el_val_t secret_key_hex, el_val_t message);
+el_val_t  pq_verify(el_val_t public_key_hex, el_val_t message, el_val_t signature_hex);
+
+el_val_t  pq_kem_keygen(void);
+el_val_t  pq_kem_encaps(el_val_t public_key_hex);
+el_val_t  pq_kem_decaps(el_val_t secret_key_hex, el_val_t ciphertext_hex);
+
+el_val_t  pq_hybrid_keygen(void);
+el_val_t  pq_hybrid_handshake(el_val_t remote_pub_combined);
+
+el_val_t  sha3_256_hex(el_val_t input);
+
+/* ── AEAD: AES-256-GCM (libcrypto-backed) ───────────────────────────────────
+ * Symmetric authenticated encryption used to wrap envelopes after a KEM
+ * handshake. Caller MUST supply a 32-byte key (64 hex chars) — typically the
+ * Kyber-768 / hybrid shared_secret, optionally normalized via SHA3-256.
+ *
+ * aead_encrypt returns a JSON map {"nonce":"...","ciphertext":"..."} where
+ * ciphertext is the AES-256-GCM output with the 16-byte auth tag appended.
+ * Nonce is a fresh 12-byte CSPRNG draw — callers never pick the nonce, which
+ * structurally rules out the GCM nonce-reuse footgun.
+ *
+ * aead_decrypt returns the plaintext String, or "" on any failure (including
+ * auth-tag mismatch). Callers MUST check for "" before trusting the result. */
+el_val_t  aead_encrypt(el_val_t key_hex, el_val_t plaintext);
+el_val_t  aead_decrypt(el_val_t key_hex, el_val_t nonce_hex, el_val_t ciphertext_hex);
+
+/* ── Native VM builtin aliases (for compiled El source) ─────────────────────
+ * These match the El VM's native_* builtins so that El source compiled
+ * to C can call the same names without modification.                */
+
+el_val_t  native_list_get(el_val_t list, el_val_t index);
+el_val_t  native_list_len(el_val_t list);
+el_val_t  native_list_append(el_val_t list, el_val_t elem);
+el_val_t  native_list_empty(void);
+el_val_t  native_list_clone(el_val_t list);
+el_val_t  native_string_chars(el_val_t s);
+el_val_t  native_int_to_str(el_val_t n);
+
+/* ── Method-call shorthand aliases ──────────────────────────────────────────
+ * The El method-call convention `obj.method(args)` compiles to
+ * `method(obj, args)`.  These aliases expose the runtime functions under
+ * the short names that result from method calls in El source.
+ *
+ * Example: `myList.append(x)` → `append(myList, x)` (calls this alias)
+ *          `myList.len()`     → `len(myList)`         (calls this alias)  */
+
+el_val_t  append(el_val_t list, el_val_t elem);   /* el_list_append */
+el_val_t  len(el_val_t list);                      /* el_list_len    */
+el_val_t  get(el_val_t list, el_val_t index);      /* el_list_get    */
+el_val_t  map_get(el_val_t map, el_val_t key);     /* el_map_get     */
+el_val_t  map_set(el_val_t map, el_val_t key, el_val_t value); /* el_map_set */
+
+/* ── OTLP/HTTP Observability ─────────────────────────────────────────────── */
+/* See bottom of el_runtime.c for the implementation.
+ * Configured by env vars OTLP_ENDPOINT, OTEL_SERVICE_NAME, OTEL_SERVICE_VERSION.
+ * No-op when OTLP_ENDPOINT is unset. Drop-on-failure semantics. */
+/* ── Subprocess execution ────────────────────────────────────────────────── */
+el_val_t exec_command(el_val_t cmd);   /* run shell command, return exit code */
+el_val_t exec_capture(el_val_t cmd);   /* run shell command, capture stdout   */
+el_val_t exec(el_val_t cmd);           /* exec(cmd) → stdout String (30s timeout) */
+el_val_t exec_bg(el_val_t cmd);        /* exec_bg(cmd) → PID String (non-blocking) */
+
+el_val_t emit_log(el_val_t level, el_val_t msg, el_val_t fields_json);
+el_val_t emit_metric(el_val_t name, el_val_t value, el_val_t tags_json);
+el_val_t trace_span_start(el_val_t name);
+el_val_t trace_span_end(el_val_t span_handle);
+el_val_t emit_event(el_val_t name, el_val_t duration_ms);
+
+#ifdef __cplusplus
+}
+#endif