fix(engram): stop startup provisioning from downgrading Engram v3

bin/gs

@@ -20,6 +20,10 @@ gs - gentle-shell on main, plus one disposable worktree per PR
                            Consumer: always the main build from gs sync.
                            Workshop: inside a gentle-shell clone or worktree, Pi
                            loads that path (gs run); elsewhere the synced clone.
+                           Pi subcommands pass through to the isolated home:
+                           gs install npm:<pkg> (e.g. npm:pi-claude-bridge),
+                           gs list. Run them outside a
+                           gentle-shell checkout, or they go through gs run.
 
   gs pr [repo] <n>         One step to review PR <n>: worktree (reused and
                            updated if it exists), then Pi on it for shell PRs

docs/gs-sync.md

@@ -80,6 +80,22 @@ Run these on each machine. A machine counts as aligned only after step 3 passes
    (confirm first that `~/.pi/agent/settings.json` does not list `git:github.com/Gentleman-Programming/gentle-pi`).
 5. Open `gs`, then the models screen: profiles appear as tabs.
 
+## Startup auto-setup is off
+
+`zsh/cortex-dotfiles.zsh` exports `GENTLE_SHELL_NO_AUTO_SETUP=1` by default.
+On startup, gentle-shell would otherwise reprovision companions, and the gentle-ai
+bundled with it (v4.3.1) replaces the active `engram` with v1.
+
+- Tradeoff: companions are no longer provisioned automatically.
+- Opt back in for one invocation with `GENTLE_SHELL_NO_AUTO_SETUP=0 gs`, or export
+  the override from `local/env.zsh`.
+- Explicit setup and installer lifecycle steps are not covered by this startup
+  guard and may still install Engram v1 until the upstream fix ships. Check
+  `engram version` afterwards. Existing terminals need `export GENTLE_SHELL_NO_AUTO_SETUP=1`
+  or a profile reload; new shells inherit the default.
+
+Check: `scripts/test-engram-auto-setup.sh`.
+
 ## Tests
 
 `tests/gs_test.sh` runs offline in a throwaway HOME with stub binaries and covers

odd/tasks/engram-host-repair.md

@@ -0,0 +1,23 @@
+# Engram host repair
+Repair Engram after Gentle Shell provisioning and audit agent-dev, agent-gentle and the current Mac.
+Preserve memory, credentials, host-specific setup and unrelated edits. Delivery: ask-on-risk; forecast <400 authored lines.
+
+## Specs
+S1. User: "arreglalo y revisa el resto de las maquinas incluida esta donde estamos ahora"
+S2. Reported failure: active `/home/jbarbat/.local/bin/engram` reports `1.20.1-0.20260902040530-5b2f08fad025` following `gs` provisioning.
+
+## Tasks
+T1 [S1-S2] Audit all three hosts, service paths and compatibility; route parent; commit `0a1d9da`; done.
+T2 [S1-S2] Repair affected installations with validated backup and recovery path; prevent recurrence via supported profile opt-out; route parent maintenance / bounded worker code; commit `0a1d9da`; done.
+T3 [S1-S2] Independently verify host compatibility and relevant launcher checks; route verifier; commit `0a1d9da`; done.
+
+## Log
+L1. User original request: "arreglalo y revisa el resto de las maquinas incluida esta donde estamos ahora"
+L2. Prior read-only SSH: agent-dev-01 active Engram at ~/.local/bin is v1, module lacks /v3. No executable observed at ~/go/bin/engram. Existing human edit zsh/zshrc must be preserved.
+L3. Audit: Mac and agent-gentle v3 and compatibility ready. agent-gentle secondary ~/go/bin/engram is v1. agent-dev on-disk v1 but running service v3, compatibility ready.
+L4. agent-dev binary-only repair: backed up v1 and running v3 at /home/jbarbat/engram-binary-repair.nf6TZb; SHA256 48c4e4803b4335cb5fd29a6e2738b51b05e1a16a1a46ad2b70b69a30a0b020fa matches /proc/870371/exe; atomically restored v3 module to ~/.local/bin/engram. No memory-store access, service restart or runtime change. Recurrence investigation pending.
+L5. Root cause independently established: package-local gentle-ai 4.3.1 provisions Engram module without /v3 after gentle-pi version changes. Supported GENTLE_SHELL_NO_AUTO_SETUP=1 blocks automatic startup provisioning; all three installed launchers have the early-return guard. Explicit setup/lifecycle install steps remain outside this mitigation.
+L6. Default opt-out deployed to all three shared profiles with targeted edits; Linux pre-edit profiles backed up in ~/engram-auto-setup-backup.*. Existing terminals need export or reload. agent-gentle secondary ~/go/bin/engram v1 preserved, not active. Mac existing zsh/zshrc edit untouched.
+L7. Test-first observed RED (beta|unset instead of beta|1), GREEN focused guard. Parent and independent verifier observed focused test, gs-sync checks and zsh syntax exit 0. Independent host checks: v3 module, ready compatibility, exported guard=1 all three. Parent regression command python3 tests/gs_official_test.py && bash tests/gs_test.sh && bash scripts/test-engram-auto-setup.sh && bash scripts/test-gs-sync.sh && git diff --check exited 0. No actual interactive gs or explicit setup launched to avoid unsafe side effects.
+L8. Assessment: RDD off, high risk item 5 environment; native assess unassessable due untracked scope, returned self-check plus independent verifier plan, both completed. No native review lifecycle run.
+L9. One focused environment work unit on fix/engram-host-repair; commit recorded below. Risk: item 5 (installed executable repair and environment setup). Forecast and actual authored lines <400. No push or PR.

scripts/test-engram-auto-setup.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+# Evaluate only the Gentle channel exports from zsh/cortex-dotfiles.zsh in a
+# clean zsh (no profile, no local env) and check defaults and overrides.
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "$0")/.." && pwd)"
+profile="$repo_root/zsh/cortex-dotfiles.zsh"
+fail() { printf 'FAIL: %s\n' "$1" >&2; exit 1; }
+
+exports="$(grep -E '^export (GENTLE_AI_CHANNEL|GENTLE_SHELL_NO_AUTO_SETUP)=' "$profile")"
+run() { env -i PATH="$PATH" "$@" zsh -f -c "$exports"$'\nprint -r -- "$GENTLE_AI_CHANNEL|${GENTLE_SHELL_NO_AUTO_SETUP-unset}"'; }
+
+[ "$(run)" = "beta|1" ] || fail "defaults: got '$(run)', want 'beta|1'"
+[ "$(run GENTLE_SHELL_NO_AUTO_SETUP=0)" = "beta|0" ] || fail "override 0 not kept: '$(run GENTLE_SHELL_NO_AUTO_SETUP=0)'"
+[ "$(run GENTLE_AI_CHANNEL=stable)" = "stable|1" ] || fail "channel override: '$(run GENTLE_AI_CHANNEL=stable)'"
+echo "PASS: engram auto-setup guard"

zsh/cortex-dotfiles.zsh

@@ -33,6 +33,13 @@ for _cortex_bin in "${_cortex_tool_bins[@]}"; do
     [[ -d "$_cortex_bin" ]] && _cortex_dotfiles_path_prepend "$_cortex_bin"
 done
 unset _cortex_tool_bins _cortex_bin
+
+# pnpm needs PNPM_HOME (or global-bin-dir) for global installs; without it
+# `pnpm add -g` fails with ERR_PNPM_NO_GLOBAL_BIN_DIR.
+if [[ -z "$PNPM_HOME" && -d "$HOME/.local/share/pnpm" ]]; then
+    export PNPM_HOME="$HOME/.local/share/pnpm"
+fi
+[[ -n "$PNPM_HOME" && -d "$PNPM_HOME" ]] && _cortex_dotfiles_path_prepend "$PNPM_HOME"
 #endregion
 
 #region Zsh Options
@@ -288,6 +295,9 @@ export CORTEX_ROOT="${CORTEX_ROOT:-$BARBATDEV_DIR/cortex/cortex}"
 export CORTEX_MULTIPLEXER="${CORTEX_MULTIPLEXER:-herdr}"
 # gs sync installs the Gentle stack from main: every host follows the beta channel.
 export GENTLE_AI_CHANNEL="${GENTLE_AI_CHANNEL:-beta}"
+# Stop gentle-shell startup auto-setup: it reprovisions companions and its
+# bundled gentle-ai replaces Engram with v1. Set to 0 to opt back in.
+export GENTLE_SHELL_NO_AUTO_SETUP="${GENTLE_SHELL_NO_AUTO_SETUP:-1}"
 #endregion
 
 #region Herdr Clipboard