gentle-pi 4.2.0 → 4.4.0

package/docs/assets/diagrams/odd-workflow.svg

@@ -1,74 +1,136 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="960" height="760" viewBox="0 0 960 760" role="img" aria-labelledby="odd-title odd-desc">
+<svg xmlns="http://www.w3.org/2000/svg" width="1000" height="500" viewBox="0 0 1000 500" role="img" aria-labelledby="odd-title odd-desc">
   <title id="odd-title">Organic Driven Development workflow</title>
   <desc id="odd-desc">One feature moves through the seven ODD protocol steps. Authorize, explore, resolve uncertainty, then classify: small understood work stays light with no durable artifacts, while substantial work is tracked in one feature document before the first write. Both paths implement task by task and close with verified proof. The same feature document carries progress across sessions so work resumes instead of restarting.</desc>
   <defs>
-    <linearGradient id="odd-bg" x1="0" y1="0" x2="1" y2="1"><stop stop-color="#100c15"/><stop offset="1" stop-color="#21101f"/></linearGradient>
-    <marker id="odd-arrow" markerUnits="userSpaceOnUse" markerWidth="10" markerHeight="10" viewBox="0 0 10 10" refX="10" refY="5" orient="auto"><path d="M0 0 10 5 0 10z" fill="#f095c8"/></marker>
+    <linearGradient id="odd-bg" x1="0" y1="0" x2="1" y2="1"><stop stop-color="#0f0b13"/><stop offset="1" stop-color="#1a0e19"/></linearGradient>
+    <radialGradient id="odd-glow" cx="0.12" cy="0" r="0.7"><stop stop-color="#f095c8" stop-opacity="0.16"/><stop offset="1" stop-color="#f095c8" stop-opacity="0"/></radialGradient>
+    <linearGradient id="odd-card" x1="0" y1="0" x2="0" y2="1"><stop stop-color="#1d1520"/><stop offset="1" stop-color="#151017"/></linearGradient>
+    <linearGradient id="odd-accent" x1="0" y1="0" x2="1" y2="1"><stop stop-color="#3a1932"/><stop offset="1" stop-color="#1e1020"/></linearGradient>
+    <pattern id="odd-dots" width="22" height="22" patternUnits="userSpaceOnUse"><circle cx="1" cy="1" r="1" fill="#ffffff" fill-opacity="0.045"/></pattern>
+    <filter id="odd-shine" x="-30%" y="-30%" width="160%" height="160%"><feGaussianBlur stdDeviation="10"/></filter>
+    <marker id="odd-arrow" markerUnits="userSpaceOnUse" markerWidth="8" markerHeight="8" viewBox="0 0 8 8" refX="7" refY="4" orient="auto"><path d="M0 0.5 7 4 0 7.5z" fill="#f095c8"/></marker>
   </defs>
-  <rect width="960" height="760" rx="20" fill="url(#odd-bg)"/>
-  <text x="40" y="65" fill="#fff7f1" font-family="Arial, Helvetica, sans-serif" font-size="44" font-weight="700">Explore, track, implement.</text>
-  <text x="40" y="120" fill="#d7a0b8" font-family="Arial, Helvetica, sans-serif" font-size="44" font-weight="700">Resume without ceremony.</text>
-  <g fill="#1c1420" stroke="#d7a0b8" stroke-width="2">
-    <rect x="40" y="170" width="196" height="120" rx="16"/>
-    <rect x="268" y="170" width="196" height="120" rx="16"/>
-    <rect x="496" y="170" width="196" height="120" rx="16"/>
-    <rect x="724" y="170" width="196" height="120" rx="16"/>
-    <rect x="724" y="330" width="196" height="120" rx="16" fill="#2a1426" stroke="#f095c8" stroke-width="3"/>
-    <rect x="610" y="490" width="196" height="120" rx="16"/>
-    <rect x="268" y="490" width="196" height="120" rx="16"/>
-  </g>
-  <rect x="496" y="330" width="196" height="120" rx="16" fill="#18121b" stroke="#d7a0b8" stroke-width="2" stroke-dasharray="6 6"/>
-  <g fill="none" stroke="#f095c8" stroke-width="3" stroke-linecap="round" marker-end="url(#odd-arrow)">
-    <path d="M236 230H268"/>
-    <path d="M464 230H496"/>
-    <path d="M692 230H724"/>
-    <path d="M822 290V330"/>
-    <path d="M822 290V310H594V330"/>
-    <path d="M708 470V490"/>
-    <path d="M610 550H464"/>
-  </g>
-  <g fill="none" stroke="#f095c8" stroke-width="3" stroke-linecap="round">
-    <path d="M594 450V470H708"/>
-    <path d="M822 450V470H708"/>
-  </g>
-  <g font-family="Arial, Helvetica, sans-serif" font-size="20" fill="#d7a0b8" opacity="0.85">
-    <text x="56" y="198">01</text>
-    <text x="284" y="198">02</text>
-    <text x="512" y="198">03</text>
-    <text x="740" y="198">04</text>
-    <text x="740" y="358">05</text>
-    <text x="626" y="518">06</text>
-    <text x="284" y="518">07</text>
-  </g>
-  <g font-family="Arial, Helvetica, sans-serif" text-anchor="middle">
-    <g fill="#fff7f1" font-size="30" font-weight="700">
-      <text x="138" y="222">Authorize</text>
-      <text x="366" y="222">Explore</text>
-      <text x="594" y="222">Resolve</text>
-      <text x="822" y="222">Classify</text>
-      <text x="822" y="382">Track</text>
-      <text x="594" y="382">Stay light</text>
-      <text x="708" y="542">Implement</text>
-      <text x="366" y="542">Close</text>
+
+  <!-- canvas -->
+  <rect width="1000" height="500" rx="24" fill="url(#odd-bg)"/>
+  <rect width="1000" height="500" rx="24" fill="url(#odd-dots)"/>
+  <rect width="1000" height="500" rx="24" fill="url(#odd-glow)"/>
+  <rect x="0.5" y="0.5" width="999" height="499" rx="23.5" fill="none" stroke="#f095c8" stroke-opacity="0.16"/>
+
+  <g font-family="ui-sans-serif, -apple-system, BlinkMacSystemFont, 'Segoe UI', Inter, Roboto, 'Helvetica Neue', Arial, sans-serif">
+
+    <!-- eyebrow -->
+    <text x="36" y="52" fill="#f095c8" font-size="12.5" font-weight="700" letter-spacing="2.6">ORGANIC DRIVEN DEVELOPMENT</text>
+    <text x="964" y="52" fill="#8e7987" font-size="13" text-anchor="end">small work stays light · substantial work gets tracked</text>
+
+    <!-- phase brackets -->
+    <g fill="#8e7987" font-size="11" font-weight="700" letter-spacing="2" text-anchor="middle">
+      <text x="220" y="94">UNDERSTAND</text>
+      <text x="552" y="94">DECIDE</text>
+      <text x="844" y="94">DELIVER</text>
     </g>
-    <g fill="#d7a0b8" font-size="22">
-      <text x="138" y="262">read-only</text>
-      <text x="366" y="262">code and needs</text>
-      <text x="594" y="262">uncertainty</text>
-      <text x="822" y="262">substantial?</text>
-      <text x="822" y="422">one document</text>
-      <text x="594" y="422">small work</text>
-      <text x="708" y="582">task by task</text>
-      <text x="366" y="582">verified proof</text>
+    <g fill="none" stroke="#f095c8" stroke-opacity="0.28" stroke-width="1">
+      <path d="M36 110V104H404V110"/>
+      <path d="M420 110V104H684V110"/>
+      <path d="M724 110V104H964V110"/>
     </g>
-  </g>
-  <g font-family="Arial, Helvetica, sans-serif" font-size="22" fill="#d7a0b8">
-    <text x="708" y="302" text-anchor="middle">small</text>
-    <text x="838" y="316" text-anchor="start">substantial</text>
-  </g>
-  <rect x="40" y="650" width="880" height="90" rx="16" fill="#18121b" stroke="#d7a0b8" stroke-width="2" stroke-dasharray="8 7"/>
-  <g font-family="Arial, Helvetica, sans-serif" text-anchor="middle">
-    <text x="480" y="686" fill="#fff7f1" font-size="34" font-weight="700">Resume where you stopped</text>
-    <text x="480" y="722" fill="#d7a0b8" font-size="26">One feature document, mirrored in Engram across sessions.</text>
+
+    <!-- flow lines -->
+    <g fill="none" stroke="#f095c8" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" marker-end="url(#odd-arrow)">
+      <path d="M148 250H162"/>
+      <path d="M276 250H290"/>
+      <path d="M404 250H418"/>
+      <path d="M532 250H544Q552 250 552 242V200Q552 192 560 192H570"/>
+      <path d="M532 250H544Q552 250 552 258V300Q552 308 560 308H570"/>
+      <path d="M684 192H696Q704 192 704 200V242Q704 250 712 250H722"/>
+      <path d="M684 308H696Q704 308 704 300V258Q704 250 712 250H722"/>
+      <path d="M836 250H850"/>
+    </g>
+    <path d="M628 386V410" fill="none" stroke="#f095c8" stroke-opacity="0.45" stroke-width="1.5" stroke-dasharray="2 5" stroke-linecap="round"/>
+
+    <!-- branch labels -->
+    <g fill="#c99bb4" font-size="12" font-weight="600" letter-spacing="0.6" text-anchor="middle">
+      <text x="628" y="134">small</text>
+      <text x="628" y="378">substantial</text>
+    </g>
+
+    <!-- accent glows -->
+    <g fill="#f095c8" opacity="0.22" filter="url(#odd-shine)">
+      <rect x="430" y="204" width="92" height="92" rx="16"/>
+      <rect x="582" y="270" width="92" height="76" rx="16"/>
+    </g>
+
+    <!-- cards -->
+    <g stroke-width="1">
+      <rect x="36" y="194" width="112" height="112" rx="14" fill="url(#odd-card)" stroke="#f095c8" stroke-opacity="0.22"/>
+      <rect x="164" y="194" width="112" height="112" rx="14" fill="url(#odd-card)" stroke="#f095c8" stroke-opacity="0.22"/>
+      <rect x="292" y="194" width="112" height="112" rx="14" fill="url(#odd-card)" stroke="#f095c8" stroke-opacity="0.22"/>
+      <rect x="420" y="194" width="112" height="112" rx="14" fill="url(#odd-accent)" stroke="#f095c8" stroke-width="1.5"/>
+      <rect x="572" y="144" width="112" height="96" rx="14" fill="#130e15" stroke="#d7a0b8" stroke-opacity="0.55" stroke-dasharray="5 5"/>
+      <rect x="572" y="260" width="112" height="96" rx="14" fill="url(#odd-accent)" stroke="#f095c8" stroke-width="1.5"/>
+      <rect x="724" y="194" width="112" height="112" rx="14" fill="url(#odd-card)" stroke="#f095c8" stroke-opacity="0.22"/>
+      <rect x="852" y="194" width="112" height="112" rx="14" fill="url(#odd-card)" stroke="#f095c8" stroke-opacity="0.45"/>
+    </g>
+
+    <!-- step numbers -->
+    <g fill="#f095c8" fill-opacity="0.13">
+      <rect x="48" y="206" width="30" height="18" rx="9"/>
+      <rect x="176" y="206" width="30" height="18" rx="9"/>
+      <rect x="304" y="206" width="30" height="18" rx="9"/>
+      <rect x="432" y="206" width="30" height="18" rx="9" fill-opacity="0.26"/>
+      <rect x="584" y="272" width="30" height="18" rx="9" fill-opacity="0.26"/>
+      <rect x="736" y="206" width="30" height="18" rx="9"/>
+      <rect x="864" y="206" width="30" height="18" rx="9"/>
+    </g>
+    <g fill="#f5b8da" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="11" font-weight="700" text-anchor="middle">
+      <text x="63" y="219">01</text>
+      <text x="191" y="219">02</text>
+      <text x="319" y="219">03</text>
+      <text x="447" y="219">04</text>
+      <text x="599" y="285">05</text>
+      <text x="751" y="219">06</text>
+      <text x="879" y="219">07</text>
+    </g>
+
+    <!-- icons (24px grid) -->
+    <g fill="none" stroke="#f095c8" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round">
+      <g transform="translate(116 203) scale(0.8)"><path d="M12 3 19 6v5c0 4.5-3 8-7 10-4-2-7-5.5-7-10V6z"/><path d="M9 12l2 2 4-4"/></g>
+      <g transform="translate(244 203) scale(0.8)"><circle cx="11" cy="11" r="6"/><path d="M15.5 15.5 20 20"/></g>
+      <g transform="translate(372 203) scale(0.8)"><path d="M4 5h16v11h-9l-4 4v-4H4z"/><path d="M10 9.2a2 2 0 1 1 2.6 1.9c-.4.2-.6.5-.6.9"/><path d="M12 13.6v.1"/></g>
+      <g transform="translate(500 203) scale(0.8)"><path d="M12 3l9 9-9 9-9-9z"/><path d="M12 8v5M12 16v.1"/></g>
+      <g transform="translate(652 153) scale(0.8)"><path d="M20 4C12 4 6 10 6 18"/><path d="M6 18c8 0 14-6 14-14"/><path d="M4 20l2-2M9 15l6-6"/></g>
+      <g transform="translate(652 269) scale(0.8)"><path d="M7 3h7l5 5v13H7z"/><path d="M14 3v5h5M10 13h6M10 17h6"/></g>
+      <g transform="translate(804 203) scale(0.8)"><path d="M9 8l-4 4 4 4M15 8l4 4-4 4"/></g>
+      <g transform="translate(932 203) scale(0.8)"><circle cx="12" cy="12" r="9"/><path d="M8 12.5l3 2.5 5-5.5"/></g>
+    </g>
+
+    <!-- titles -->
+    <g fill="#fbeff5" font-size="17" font-weight="650">
+      <text x="48" y="266">Authorize</text>
+      <text x="176" y="266">Explore</text>
+      <text x="304" y="266">Resolve</text>
+      <text x="432" y="266">Classify</text>
+      <text x="584" y="202">Stay light</text>
+      <text x="584" y="318">Track</text>
+      <text x="736" y="266">Implement</text>
+      <text x="864" y="266">Close</text>
+    </g>
+    <g fill="#a8939f" font-size="12.5">
+      <text x="48" y="288">read-only</text>
+      <text x="176" y="288">code and needs</text>
+      <text x="304" y="288">uncertainty</text>
+      <text x="432" y="288">substantial?</text>
+      <text x="584" y="222">small work</text>
+      <text x="584" y="338">one document</text>
+      <text x="736" y="288">task by task</text>
+      <text x="864" y="288">verified proof</text>
+    </g>
+
+    <!-- resume band -->
+    <rect x="36" y="410" width="928" height="56" rx="14" fill="#f095c8" fill-opacity="0.06" stroke="#f095c8" stroke-opacity="0.22"/>
+    <g fill="none" stroke="#f095c8" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" transform="translate(56 426) scale(1)">
+      <path d="M20 12a8 8 0 1 1-2.3-5.6"/><path d="M20 4v5h-5"/>
+    </g>
+    <text x="92" y="443" font-size="15.5"><tspan fill="#fbeff5" font-weight="650">Resume where you stopped</tspan><tspan fill="#a8939f" dx="10">One feature document, mirrored in Engram across sessions.</tspan></text>
   </g>
 </svg>

package/docs/assets/diagrams/permission-modes.svg

@@ -0,0 +1,51 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1000" height="400" viewBox="0 0 1000 400" role="img" aria-labelledby="modes-title modes-desc">
+  <title id="modes-title">Permission modes</title>
+  <desc id="modes-desc">Three permission modes. Normal keeps the standard prompts. Auto checks eligible actions with an independent inference using the current session model; ordinary checks are tool-free, an eligible script check can inspect at most two complete files, and unavailable or stale decisions do not run the action. YOLO gives standing permission for ordinary already-scoped work while destructive actions still ask. In every mode, explicit restrictions, destructive guards, and independent consent remain, and none of the modes is a sandbox.</desc>
+  <defs>
+    <linearGradient id="modes-bg" x1="0" y1="0" x2="1" y2="1"><stop stop-color="#0f0b13"/><stop offset="1" stop-color="#1a0e19"/></linearGradient>
+    <radialGradient id="modes-glow" cx="0.12" cy="0" r="0.7"><stop stop-color="#f095c8" stop-opacity="0.16"/><stop offset="1" stop-color="#f095c8" stop-opacity="0"/></radialGradient>
+    <linearGradient id="modes-card" x1="0" y1="0" x2="0" y2="1"><stop stop-color="#1d1520"/><stop offset="1" stop-color="#151017"/></linearGradient>
+    <linearGradient id="modes-accent" x1="0" y1="0" x2="1" y2="1"><stop stop-color="#3a1932"/><stop offset="1" stop-color="#1e1020"/></linearGradient>
+    <linearGradient id="modes-bar" x1="0" y1="0" x2="1" y2="0"><stop stop-color="#c46b9e"/><stop offset="1" stop-color="#f095c8"/></linearGradient>
+    <pattern id="modes-dots" width="22" height="22" patternUnits="userSpaceOnUse"><circle cx="1" cy="1" r="1" fill="#ffffff" fill-opacity="0.045"/></pattern>
+    <filter id="modes-shine" x="-30%" y="-30%" width="160%" height="160%"><feGaussianBlur stdDeviation="10"/></filter>
+    <marker id="modes-arrow" markerUnits="userSpaceOnUse" markerWidth="8" markerHeight="8" viewBox="0 0 8 8" refX="7" refY="4" orient="auto"><path d="M0 0.5 7 4 0 7.5z" fill="#f095c8"/></marker>
+    <marker id="modes-arrow-soft" markerUnits="userSpaceOnUse" markerWidth="8" markerHeight="8" viewBox="0 0 8 8" refX="7" refY="4" orient="auto"><path d="M0 0.5 7 4 0 7.5z" fill="#d7a0b8"/></marker>
+  </defs>
+  <rect width="1000" height="400" rx="24" fill="url(#modes-bg)"/>
+  <rect width="1000" height="400" rx="24" fill="url(#modes-dots)"/>
+  <rect width="1000" height="400" rx="24" fill="url(#modes-glow)"/>
+  <rect x="0.5" y="0.5" width="999" height="399" rx="23.5" fill="none" stroke="#f095c8" stroke-opacity="0.16"/>
+  <g font-family="ui-sans-serif, -apple-system, BlinkMacSystemFont, 'Segoe UI', Inter, Roboto, 'Helvetica Neue', Arial, sans-serif">
+    <text x="36" y="52" fill="#f095c8" font-size="12.5" font-weight="700" letter-spacing="2.6">PERMISSION MODES</text>
+    <text x="964" y="52" fill="#8e7987" font-size="13" text-anchor="end">/gentle:mode · /gentle:yolo</text>
+    <path d="M36 96H956" stroke="#f095c8" stroke-opacity="0.35" stroke-width="1.5" marker-end="url(#modes-arrow)"/>
+    <text x="36" y="86" fill="#8e7987" font-size="11" font-weight="700" letter-spacing="0.4" text-anchor="start">more questions</text>
+    <text x="964" y="86" fill="#8e7987" font-size="11" font-weight="700" letter-spacing="0.4" text-anchor="end">fewer questions</text>
+    <rect x="36" y="120" width="288" height="160" rx="14" fill="url(#modes-card)" stroke="#f095c8" stroke-opacity="0.22"/>
+    <g transform="translate(292 129) scale(0.8)" fill="none" stroke="#f095c8" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"><rect x="5" y="11" width="14" height="10" rx="2"/><path d="M8 11V8a4 4 0 0 1 8 0v3"/></g>
+    <text x="48" y="200" fill="#fbeff5" font-size="20" font-weight="650">Normal</text>
+    <text x="48" y="222" fill="#a8939f" font-size="12.5">standard prompts</text>
+    <text x="48" y="240" fill="#a8939f" font-size="12.5">the default</text>
+    <rect x="48" y="132" width="145" height="18" rx="9" fill="#f095c8" fill-opacity="0.13"/>
+    <text x="120.4" y="145" fill="#f5b8da" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="11" font-weight="700" text-anchor="middle">/gentle:mode normal</text>
+    <rect x="356" y="120" width="288" height="160" rx="14" fill="url(#modes-card)" stroke="#f095c8" stroke-opacity="0.22"/>
+    <g transform="translate(612 129) scale(0.8)" fill="none" stroke="#f095c8" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="8"/><circle cx="12" cy="12" r="3"/></g>
+    <text x="368" y="200" fill="#fbeff5" font-size="20" font-weight="650">Auto</text>
+    <text x="368" y="222" fill="#a8939f" font-size="12.5">an independent check decides</text>
+    <text x="368" y="240" fill="#a8939f" font-size="12.5">unavailable or stale: does not run</text>
+    <rect x="368" y="132" width="130" height="18" rx="9" fill="#f095c8" fill-opacity="0.13"/>
+    <text x="433.2" y="145" fill="#f5b8da" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="11" font-weight="700" text-anchor="middle">/gentle:mode auto</text>
+    <rect x="686" y="130" width="268" height="140" rx="16" fill="#f095c8" opacity="0.22" filter="url(#modes-shine)"/>
+    <rect x="676" y="120" width="288" height="160" rx="14" fill="url(#modes-accent)" stroke="#f095c8" stroke-width="1.5"/>
+    <g transform="translate(932 129) scale(0.8)" fill="none" stroke="#f095c8" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"><path d="M13 3 5 14h6l-1 7 8-11h-6z"/></g>
+    <text x="688" y="200" fill="#fbeff5" font-size="20" font-weight="650">YOLO</text>
+    <text x="688" y="222" fill="#a8939f" font-size="12.5">standing permission for scoped work</text>
+    <text x="688" y="240" fill="#a8939f" font-size="12.5">destructive actions still ask</text>
+    <rect x="688" y="132" width="145" height="18" rx="9" fill="#f095c8" fill-opacity="0.13"/>
+    <text x="760.4" y="145" fill="#f5b8da" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="11" font-weight="700" text-anchor="middle">/gentle:yolo enable</text>
+    <rect x="36" y="308" width="928" height="56" rx="14" fill="#f095c8" fill-opacity="0.06" stroke="#f095c8" stroke-opacity="0.22"/>
+    <g transform="translate(56 324.0) scale(1)" fill="none" stroke="#f095c8" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"><path d="M12 3 19 6v5c0 4.5-3 8-7 10-4-2-7-5.5-7-10V6z"/><path d="M9 12l2 2 4-4"/></g>
+    <text x="92" y="341.5" font-size="15.5"><tspan fill="#fbeff5" font-weight="650">In every mode</tspan><tspan fill="#a8939f" dx="10">explicit restrictions, destructive guards, and independent consent remain. Not a sandbox.</tspan></text>
+  </g>
+</svg>

package/docs/bundled-install.md

@@ -13,7 +13,7 @@ The building blocks live in `scripts/bundled-install.mjs`. The web installer and
 | `~/.gentle-shell/npm/{prefix,cache}/`, `~/.gentle-shell/npm/npmrc` | npm's global prefix, cache and global config. The global config file is never written. |
 | `~/.gentle-shell/runtime/pnpm-11.1.1/package/` | Our pnpm, from the verified registry tarball. |
 | `~/.gentle-shell/runtime/go/1.25.14/go/` | Our Go, only when asked (`acquireGo` layout). |
-| `~/.gentle-shell/runtime/engram-3.4.0/engram` | Our Engram, from the verified GitHub release archive ([Isolation from the user's Gentle AI](#isolation-from-the-users-gentle-ai)). |
+| `~/.gentle-shell/runtime/engram-3.5.2/engram` | Our Engram, from the verified GitHub release archive ([Isolation from the user's Gentle AI](#isolation-from-the-users-gentle-ai)). |
 | `~/.gentle-shell/gentle-ai/` | Gentle AI's state, managed assets, backups and telemetry state (`GENTLE_AI_HOME`). |
 | `~/.gentle-shell/config/gentle-ai/` | gentle-pi's config home in a bundled install (derived, never exported to Pi): profiles, preferences, persona, background subagents. |
 | `~/.gentle-shell/pnpm/{store,cache,state,config}/` | Every folder pnpm writes. |
@@ -24,6 +24,25 @@ The building blocks live in `scripts/bundled-install.mjs`. The web installer and
 
 On Windows the same layout lives under a private folder. The module tries `%LOCALAPPDATA%\gentle-shell` first. It falls back to `%USERPROFILE%\.gentle-shell-bundle` only when an untrusted owner or ACL rejects the first folder, the same rule the bootstrap uses for its tools. The folder is claimed with the bootstrap's protected DACL and marked with `.gentle-shell-bundle` (`ensureWindowsPrivateFolder`). `current` is a pointer file holding the version id. The launcher is `bin\gentle-shell.cmd`, and `tmp\` holds TEMP and TMP for pnpm's children. The agent home stays at `%USERPROFILE%\.gentle-shell\agent`.
 
+### Windows prerequisite failure diagnostics
+
+`windowsProcessCheck` still throws exactly `Windows prerequisite process failed`
+(`process-failed` classification). Its standard Error cause preserves status,
+signal and selected process-error fields plus bounded stdout/stderr. A sanitized
+`cause.stack` also carries these fields for existing evidence consumers, without
+local callsites, raw spawn errors, commands, argv or environment snapshots.
+Process-error messages use only a sanitized native error code or fixed fallback,
+never raw spawn text that could include a private bare executable name.
+Limits are UTF-16 code units: streams1024 each, error message256, name/code/errno
+text64, signal32 and cause stack8192; numeric status/errno remain numeric.
+Path/SID, encoded ACL/opaque and control-bearing lines are suppressed; credential
+markers, including underscore-separated environment names such as `GITHUB_TOKEN`
+and `API_KEY`, suppress the entire field including continuation lines. This conservative
+filter may discard useful output and is not a general-purpose secret parser.
+Nothing prints automatically. CMD/BAT rejection, neutral cwd, shell=false,
+15-second SIGKILL/1MiB capture and all ACL/provenance checks remain unchanged.
+Elapsed time alone does not establish timeout or diagnose the historical CI failure.
+
 ## Ownership rules
 
 - **Runtimes.** Each one is downloaded through `verifiedDownload` (the existing pins and hashes), written to a staging folder and run once to check its version. It is then marked with `.gentle-shell-runtime` and published with one rename. A marked runtime is reused. An unmarked folder is never replaced. Renaming is safe here because the extracted trees hold only regular files and folders, never links. The pnpm tarball's executable bits (`bin/pnpm.mjs`, `dist/node-gyp-bin/node-gyp`) are kept, for the owner only.
@@ -229,56 +248,72 @@ Dropped: inherited npm and pnpm settings, `NODE_OPTIONS`, `NODE_PATH`, and the w
 
 ### Engram startup safety
 
-A bundled Shell decides, before setup and again right before Pi starts, whether memory may open the shared Engram store. When it may not, Shell keeps working without memory and **points `ENGRAM_BIN` at its own guard**, so no provider, whichever Pi route loaded it, can open, create or migrate a store it cannot vouch for. The core pin is **3.4.0**, acquired through the existing size- and checksum-verified path.
+A bundled Shell shares the global Engram server, like other agents' hooks: it reuses a verified server already listening on the default endpoint and, when nothing listens, starts one itself with its verified bundled core. It decides before setup and again right before Pi starts. When memory may not be used, Shell keeps working without memory and **points `ENGRAM_BIN` at its own guard**, so no provider, whichever Pi route loaded it, can open, create or migrate a store directly. The core pin is **3.5.2**, acquired through the existing size- and checksum-verified path.
 
 #### Decision
 
 | Evidence (default `~/.engram`, default endpoint `127.0.0.1:7437`) | Memory | `ENGRAM_BIN` / `ENGRAM_URL` |
 |---|---|---|
-| No data directory, nothing listening, verified bundled core | Allowed; this launch provisions a fresh store | Bundled core |
-| Same, but the bundled core is missing or unverified | Disabled | Guard (never an `engram` from `PATH`) |
-| Running server answers the exact `GET /compatibility` ready contract | Allowed; reuse that server | Guard + `ENGRAM_URL=http://127.0.0.1:7437` |
-| Shell's own store (provenance below), nothing listening | Allowed | Bundled core |
-| Shell's own store, server listening with `/health` `instance_id` = recorded id **and** `version` = the exact bundled core version | Allowed | Bundled core |
-| Anything else: foreign or unreadable data, provenance mismatch, a different server, timeout, 401/404, malformed answers | Disabled | Guard |
-| Explicit `ENGRAM_BIN`, `ENGRAM_URL`, `ENGRAM_PORT`, `ENGRAM_DATA_DIR`, `ENGRAM_DATABASE_URL`, or an invalid `ENGRAM_STARTUP_POLICY` | Disabled, never probed | Explicit `ENGRAM_BIN`/`ENGRAM_URL` kept; `ENGRAM_URL` alone gets the verified core (or the guard) as `ENGRAM_BIN`; otherwise guard |
-
-Classification never runs an Engram executable (`instance-id`, `version`, `serve`), never opens SQLite, and never infers compatibility from a version string. It reads file metadata, the `.instance-id` file, the raw database header, and makes bounded (1 s) read-only `GET /compatibility` and `GET /health` requests to the default endpoint on a direct loopback socket, without proxy, redirects or credentials. `gentle-shell --version` and a Pi version or help flag (`--version`, `-v`, `--help`, `-h` where Pi reads it as a flag: before Pi's own `--` and not as another option's value, so a prompt or option value containing `-v` does not count) never probe, ensure the companion, print memory notices or touch provenance.
+| Running server answers the exact `GET /compatibility` ready contract | Allowed; reuse that server unchanged | Guard + `ENGRAM_URL=http://127.0.0.1:7437` |
+| Nothing listening, verified bundled core | Allowed once the server Shell starts (below) answers ready; otherwise disabled for that launch | Guard + `ENGRAM_URL=http://127.0.0.1:7437` |
+| Nothing listening, but `engram.db`'s header `user_version` is newer than the bundled core's schema | Disabled; no server is started | Guard |
+| Nothing listening, but the bundled core is missing or unverified | Disabled | Guard (never an `engram` from `PATH`) |
+| Anything else listening: a different service, timeout, 401/404, an older server, malformed answers | Disabled; the listener is never stopped or replaced | Guard |
+| Explicit `ENGRAM_BIN`, `ENGRAM_URL`, `ENGRAM_PORT`, `ENGRAM_SOCKET`, `ENGRAM_DATA_DIR`, `ENGRAM_DATABASE_URL`, `ENGRAM_SERVER_MODE`, or an invalid `ENGRAM_STARTUP_POLICY` | Disabled, never probed or started | Explicit `ENGRAM_BIN`/`ENGRAM_URL` kept; `ENGRAM_URL` alone gets the verified core (or the guard) as `ENGRAM_BIN`; otherwise guard |
 
-#### The guard
+An existing store at `~/.engram` does not disable memory by itself, whoever created it (an earlier Shell or the global Engram CLI): the server owns the store, and Shell only talks to a server that proves itself through `/compatibility`. The one exception is the header tripwire: when `engram.db` is a regular, unlinked file whose first 100 bytes are a valid SQLite header (magic, page size, bytes 18/19 each 1 or 2) and whose `user_version` (bytes 60-63) is **greater** than the bundled core's schema (`1`, verified from `v3.5.2:internal/store/store.go`), a newer Engram migrated the store, so Shell does not start its older core on it. Start that newer Engram's server yourself; Shell then reuses it. A pin without a verified schema entry treats any readable header as newer. Equal or lower (including a stale `0` before a WAL checkpoint) is no signal either way.
 
-`bin/engram-guard` is a POSIX `sh` script, run directly (no shell needed by the caller). It ignores its arguments, prints `ENGRAM_STARTUP_NOTICE` (as data, never executed) to stderr and exits 78. It never runs Engram and never reads or writes Engram data. gentle-engram 0.4.1 reaches local data only by running `ENGRAM_BIN` (`instance-id` first, before any health probe or spawn), so the guard stops it before any store access; 0.4.2 also honors `ENGRAM_STARTUP_POLICY=disabled`. Pi, its subagents and the agent's shell all inherit the same environment.
+Classification never runs an Engram executable, never opens SQLite, and never infers compatibility from a version string. It reads the raw database header and makes bounded (1 s) read-only `GET /compatibility` and `GET /health` requests to the default endpoint on a direct loopback socket, without proxy, redirects or credentials. `gentle-shell --version` and a Pi version or help flag (`--version`, `-v`, `--help`, `-h` where Pi reads it as a flag: before Pi's own `--` and not as another option's value, so a prompt or option value containing `-v` does not count) never probe, start a server, ensure the companion or print memory notices. A Pi subcommand (`gentle-shell list`, `install`, ...) and `gentle-shell setup` never start a server either.
 
-- **Explicit selections bypass the guard.** An `ENGRAM_BIN` or `ENGRAM_URL` you set is never replaced or removed (with only `ENGRAM_URL`, `ENGRAM_BIN` is still the verified core, or the guard without one, never a `PATH` engram); memory is still marked disabled through the policy, which only 0.4.2+ honors.
-- **Windows.** The guard has no `.exe`; spawning it fails (for example `ENOENT` or `EINVAL`), which still fails closed, but no notice is printed.
+#### Starting the shared server
 
-#### Provenance (Shell's own store)
+Only the final pre-Pi decision starts a server. Shell runs the verified bundled core as plain `engram serve`, with Engram's own default port and data directory, **detached** (its own process group, `stdio` ignored, unreferenced, `windowsHide` on Windows, working directory the home folder), so it outlives Pi like a server other agents' hooks start. Its environment is the user's minus every `ENGRAM_*` setting and `GH_TOKEN`/`GITHUB_TOKEN`, plus `ENGRAM_NO_UPDATE_CHECK=1`. For `TMPDIR`/`TMP`/`TEMP` whose final path component is session scratch (`gp` or `ga` followed by exactly six alphanumeric characters), POSIX drops the setting. Windows instead explicitly replaces it with its original absolute ancestor outside consecutive scratch components: omitting `TEMP` can cause Node to inherit the parent's scratch again. When any Windows scratch setting is replaced and `TEMP` is absent, Shell also sets `TEMP` to that stable ancestor. Existing custom temp settings retain their own values, even when they name different roots. Windows path separators and case-insensitive environment keys are supported. An unsafe relative scratch path disables this startup attempt before spawning; Shell never guesses a root or creates a temp folder. Unrelated variables remain unchanged. Pi keeps the user's environment. Shell then polls `GET /compatibility` for up to 10 seconds. A ready answer allows memory through the reuse URL; otherwise (the core fails to start, exits, or never answers ready) memory is disabled for that launch with a notice, and Shell still starts Pi. Concurrent launches converge: when the child exits (for example because another launch won the bind), Shell keeps polling for a short grace, and a ready `/compatibility` from the winner counts as started. Shell never stops a server it started or found; it keeps running for every client until you stop it.
 
-When the final pre-Pi decision is "fresh" (no data directory, nothing listening, verified bundled core, no explicit selection), Shell provisions the store identity itself **before** Pi starts: it runs the verified bundled core's `instance-id` (15 s timeout) with the environment Pi will use, except that this one invocation gets `ENGRAM_NO_UPDATE_CHECK=1` and no `GH_TOKEN`/`GITHUB_TOKEN`. In Engram 3.4.0 that command only creates the data directory, `.instance-id.lock` and `.instance-id`; it skips orphan migration and opens no database. Shell then reads the `.instance-id` **file** (regular, not a link, a valid id equal to the command's output, in the same default directory it classified as absent) and immediately writes `<prefix>/config/engram-provenance.json` (mode 0600): the canonical data directory, that instance id, and the sha256 of the bundled core. If any step fails (the command fails or times out, the identity is invalid, or the record cannot be written), memory is disabled for that launch behind the guard; Pi never starts with memory allowed without a written record. Shell never records a store it did not provision, so a store that appears later at the default directory is never adopted.
+#### The guard
 
-A later launch treats the store as Shell's own only when all hold:
+`bin/engram-guard` is a POSIX `sh` script, run directly (no shell needed by the caller). It ignores its arguments, prints `ENGRAM_STARTUP_NOTICE` (as data, never executed) to stderr and exits 78. It never runs Engram and never reads or writes Engram data. gentle-engram 0.4.1 reaches local data only by running `ENGRAM_BIN` (`instance-id` first, before any health probe or spawn), so the guard stops it before any store access; 0.4.2 also honors `ENGRAM_STARTUP_POLICY=disabled`, and with `ENGRAM_URL` it talks to the shared server over HTTP. Pi, its subagents and the agent's shell all inherit the same environment.
 
-1. The data directory, its `.instance-id` and the current bundled core digest equal the record. A Shell upgrade that changes the core binary therefore disables memory: forward upgrades are not allowed by version.
-2. The directory still holds only identity files (the session has not created a database yet), or `engram.db` is a regular, unlinked file whose first 100 bytes are a valid SQLite header (magic, page size, bytes 18/19 each 1 or 2) and whose `user_version` (bytes 60-63) is **not greater** than the bundled core's schema (`1`, verified from `v3.4.0:internal/store/store.go`). A greater value means a newer Engram migrated the shared store. Equal or lower (including a stale `0` before a WAL checkpoint) is no signal either way. A pin without a verified schema entry disables this path.
-3. If a server listens, its `/health` reports the recorded instance and exactly the bundled core version.
+- **Explicit selections bypass the guard.** An `ENGRAM_BIN` or `ENGRAM_URL` you set is never replaced or removed (with only `ENGRAM_URL`, `ENGRAM_BIN` is still the verified core, or the guard without one, never a `PATH` engram); memory is still marked disabled through the policy, which only 0.4.2+ honors. An `ENGRAM_SERVER_MODE` you set is passed through untouched; Shell never selects one.
+- **Windows.** The guard has no `.exe`; spawning it fails (for example `ENOENT` or `EINVAL`), which still fails closed, but no notice is printed.
 
 #### Compatible reuse and authorization
 
-`GET /compatibility` (published in Engram 3.4.0 through PR #1792; 3.3.2 answers 404) must return `status: "ready"`, `active_reuse_authorized: true`, `capability: "startup-verified-store-v1"`, `revision: 1`, `source: "active"`, 32-hex `instance_id` and `runtime_id`, and no `offline_automatic_opening_authorized: true`. The endpoint uses the server's `requireAuth`: open when the **server** has no `ENGRAM_HTTP_TOKEN`, otherwise it needs `Authorization: Bearer <token>`. Shell owns no such secret and sends none, so a token-protected server answers 401 and stays unknown (disabled).
+`GET /compatibility` (published in Engram 3.4.0 through PR #1792; 3.3.2 answers 404) must return `status: "ready"`, `active_reuse_authorized: true`, `capability: "startup-verified-store-v1"`, `revision: 1`, `source: "active"`, 32-hex `instance_id` and `runtime_id`, and no `offline_automatic_opening_authorized: true`. Engram 3.5.2's plain `serve` answers exactly this. The endpoint uses the server's `requireAuth`: open when the **server** has no `ENGRAM_HTTP_TOKEN`, otherwise it needs `Authorization: Bearer <token>`. Shell owns no such secret and sends none, so a token-protected server answers 401 and stays unknown (disabled). The server Shell starts never inherits `ENGRAM_HTTP_TOKEN`.
 
 #### Recovery and setup
 
-When the running server's `/health` reports a valid 32-hex `instance_id` and a canonical numeric `x.y.z` version (optional `v` prefix, no leading zeros, at most four digits per component) older than 3.4.0, and `/compatibility` does not answer ready, the notice names that version and asks to back up the data, update **that server** to 3.4.0 or later with its own installation method, and restart it. The version only selects this wording: memory stays disabled, and any other version string is never shown. Otherwise, when disabled, Shell explains that it **could not verify safe store or server reuse**. Matching versions or updating alone do not prove compatibility. Reuse requires the verified active `/compatibility` contract or matching Shell-provisioned store identity under the rules above. Back up existing data before manual changes; do not delete the store, fabricate provenance, or bypass the safety check. Shell rechecks on every launch and remains usable without memory. It performs no migration, deletion, or process termination.
+When the running server's `/health` reports a valid 32-hex `instance_id` and a canonical numeric `x.y.z` version (optional `v` prefix, no leading zeros, at most four digits per component) older than 3.4.0, and `/compatibility` does not answer ready, the notice names that version and asks to back up the data, update **that server** to 3.4.0 or later with its own installation method, and restart it. The version only selects this wording: memory stays disabled, and any other version string is never shown. Otherwise, when disabled, Shell explains that it **could not verify safe server reuse**. Matching versions or updating alone do not prove compatibility. Back up existing data before manual changes; do not delete the store or bypass the safety check. Shell rechecks on every launch and remains usable without memory. Ordinary startup performs no migration, deletion, or process termination.
 
 Engram 3.3.2 does not expose `/compatibility`, so reinstalling that version cannot authorize reuse of an existing global store. [Engram 3.4.0](https://github.com/Gentleman-Programming/engram/releases/tag/v3.4.0) includes the endpoint from PR #1792. Back up the existing store before updating its server through its own installation method, then restart that server and Shell. Updating Shell's bundled binary does not replace an already-running global server. Reuse still requires a valid ready response, not just the version number; a token-protected server cannot provide it to Shell's unauthenticated probe. Do not disable authentication to bypass this policy or use an unpublished build.
 
-The memory decision never skips or fails setup: `gentle-shell setup` always publishes the verified core, runs Gentle AI and pins the companion, as before. Gentle AI 4.0.0 `install --agent pi` runs no `engram setup` for Pi, and `pi-engram init` only edits settings, so neither opens a store. Setup reclassifies after publishing the core, and the decision only selects the Engram environment its children and the launched Pi receive. On a new machine the wizard publishes the runtime without Engram, so the first `gentle-shell setup` publishes the core and the following launch is the fresh one that records provenance. Setup and every launch pin `npm:gentle-engram@0.4.2` through Pi's own `install` command (configuration only) and verify the declaration plus `engram.startupPolicy: 1`; a failed check is reported and Shell still starts, protected by the guard. `setup --dry-run` installs nothing.
+The memory decision never skips or fails setup: `gentle-shell setup` always publishes the verified core, runs Gentle AI and pins the companion, as before. Gentle AI 4.0.0 `install --agent pi` runs no `engram setup` for Pi, and `pi-engram init` only edits settings, so neither opens a store. Setup reclassifies after publishing the core, and the decision only selects the Engram environment its children and the launched Pi receive. On a new machine the wizard publishes the runtime without Engram, so the first `gentle-shell setup` publishes the core and the following launch starts the shared server. Setup and every launch pin `npm:gentle-engram@0.4.2` through Pi's own `install` command (configuration only) and verify the declaration plus `engram.startupPolicy: 1`; a failed check is reported and Shell still starts, protected by the guard. `setup --dry-run` installs nothing.
+
+#### Explicit recovery after a core upgrade
+
+Earlier Shell releases provisioned `~/.engram` themselves and recorded `<prefix>/config/engram-provenance.json`; ordinary startup no longer reads that record. To migrate such a **Shell-provisioned store** with the bundled core explicitly, stop every Engram client and server using the directory, retain a complete backup (including WAL and configuration), then run:
+
+```sh
+gentle-shell memory migrate --confirm-quiescent
+```
+
+**Release dependency:** this requires a published bundled core advertising `migrate-copy`. The pinned Engram 3.5.2 implements it; Engram 3.4.0 did not. Shell checks help in an isolated home and refuses without invoking an unknown migration command or changing the source/provenance. Do not substitute an unpublished binary, edit hashes, or assume equal schema versions authorize recovery.
+
+When supported, the provider copies the complete directory to a new sibling and validates/migrates only that copy. Shell checks the provider's directory and identity evidence, renames the original to the reported `backup_dir`, promotes the copy, and atomically replaces its core-bound provenance. Success prints one JSON record with `status: "migrated"`, `instance_id`, and `backup_dir`. Keep that backup until you have verified your records in Shell. Provider failures preserve the original and provenance; any incomplete copy is identified and retained, never promoted. Explicit foreign data locations or endpoints are not adopted by this command.
+
+The confirmation is an operator assertion, not a process lock: source hashes detect observed changes but do not establish that every writer has stopped. Never run recovery while another integration is using the store.
+
+#### Recovering an interrupted migration
+
+A marker at `<prefix>/config/engram-migration.json` blocks memory before probes or starting a server. It records the `source`, `output`, `backup` paths and `originalProvenance`. **Keep clients stopped and do not simply remove this marker.** Preserve all paths while inspecting them.
+
+To roll back an interrupted promotion, first verify the paths and recorded instance identity. If `backup` exists, it is the original directory: retain any current `source` under a separate quarantine name, then restore `backup` to `source`. If no backup exists, do not replace the original source with the incomplete output. Restore `originalProvenance` atomically to `<prefix>/config/engram-provenance.json`, preserving the old core hash exactly. Only after source identity and provenance are reconciled may the marker be removed. Retain the migration output for diagnosis. If these facts cannot be established, leave the marker and request recovery assistance rather than guessing.
+
+No automatic retry, store deletion, or server termination is performed.
 
 #### Known limits
 
-- **Shared-store residuals.** Provenance proves Shell's core created the store, not that no other Engram opened it since. A different Engram that changed the store without raising `user_version` (for example same-schema repairs) is not detected without reading the database, and changes still only in the WAL are not visible in the header.
-- **Concurrent creation.** Another client that uses Shell's freshly provisioned directory (same `.instance-id`) during or after the session is not distinguishable from Shell's own core, beyond the header check. A held identity lock makes provisioning time out and disables memory for that launch.
-- **Failed provisioning.** If the identity was created but the record could not be written, later launches see an unrecorded store and keep memory disabled; the notice explains how to recover.
+- **Shared-store residuals.** The header tripwire only sees a newer schema recorded in `engram.db`'s header. A different Engram that changed the store without raising `user_version`, or changes still only in the WAL, are not detected without reading the database; the server that opens the store owns its migrations.
+- **A detached server keeps running.** The server Shell starts is not tied to Pi's lifetime, by design (it is shared). Stop it like any Engram server when you no longer want it; Shell starts it again on the next launch if nothing listens.
 - **Older or other integrations.** gentle-engram versions before 0.4.1, and integrations that do not reach data through `ENGRAM_BIN` (for example an MCP launcher running `engram` from `PATH`), are not covered by the guard.
 - **Non-bundled installs** keep their previous behavior.
 
@@ -289,7 +324,7 @@ S9. Everything Gentle AI and gentle-pi keep lives in the prefix, except Engram's
 | Process | Gets |
 |---|---|
 | `gentle-shell setup` (the pinned `gentle-ai install --agent pi`) | `GENTLE_AI_HOME=<prefix>/gentle-ai`, `GENTLE_AI_PI_CONFIG_DIR=<prefix>/config/gentle-ai`, `GENTLE_AI_ENGRAM_BIN=<prefix>/runtime/engram-<v>/engram`, `GENTLE_AI_NO_SELF_UPDATE=1` and `GENTLE_PI_CONFIG_HOME=<prefix>/config`. |
-| Pi and its subagents | `GENTLE_SHELL_PREFIX=<prefix>` and the memory startup policy; `ENGRAM_BIN` is the verified `<prefix>/runtime/engram-<v>/engram` when memory is allowed locally, otherwise the Shell guard (plus `ENGRAM_URL` for verified reuse). An explicit `ENGRAM_BIN` or `ENGRAM_URL` is kept as is ([Engram startup safety](#engram-startup-safety)). No `GENTLE_AI_*` variable, and `GENTLE_PI_CONFIG_HOME` is left as the user has it. |
+| Pi and its subagents | `GENTLE_SHELL_PREFIX=<prefix>` and the memory startup policy; `ENGRAM_BIN` is the Shell guard, plus `ENGRAM_URL=http://127.0.0.1:7437` when the shared server is verified. An explicit `ENGRAM_BIN` or `ENGRAM_URL` is kept as is ([Engram startup safety](#engram-startup-safety)). No `GENTLE_AI_*` variable, and `GENTLE_PI_CONFIG_HOME` is left as the user has it. |
 | gentle-pi's own `gentle-ai` runs (review, telemetry trigger, runtime metrics) | The same five variables as setup. |
 | The agent's shell | Pi's environment: the user's own plus the Pi row above. |
 
@@ -299,10 +334,10 @@ S9. Everything Gentle AI and gentle-pi keep lives in the prefix, except Engram's
   - **Aligned with Gentle AI 4.0.0.** Gentle AI 4.0.0 reads `GENTLE_PI_CONFIG_HOME` as the parent of its own `gentle-ai` folder: `piBackgroundPolicyPath` in `internal/cli/pi_background.go` writes `<GENTLE_PI_CONFIG_HOME>/gentle-ai/background-subagents.json`, else `~/.pi/gentle-ai/...`. So the config home is `<prefix>/config/gentle-ai`, and only the Gentle AI processes Gentle Shell starts also get `GENTLE_PI_CONFIG_HOME=<prefix>/config`. The policy 4.0.0 writes during setup then lands in the bundled config home, and a release with gentle-ai#5462 writes the same folder through `GENTLE_AI_PI_CONFIG_DIR`. In 4.0.0 only `install`, `sync` and their dry runs read it (the background-policy projection); review and telemetry runs do not, and get it only so every Gentle AI process Gentle Shell starts agrees.
 - **Gentle AI's variables never reach Pi.** Pi's bash tool would pass them to a `gentle-ai` the user runs in the agent's shell, and that run would then use the prefix. Instead, `gentleAiIsolationEnv` (`lib/gentle-ai-binary.ts`) adds them to each `gentle-ai` that a bundled gentle-pi starts itself (the central `gentleAiProcessEnvironment`, the review relay, the runtime metrics send and the telemetry trigger), and the launcher adds them to setup. `GENTLE_AI_ENGRAM_BIN` is set only when our Engram is published.
 - **Engram.** `ensureEngram` (`scripts/bundled-install.mjs`) publishes the pinned Engram release under `runtime/engram-<v>/`. The archive is checked against its pinned size and sha256 from the release's `checksums.txt`. Only the `engram` (or `engram.exe`) regular file is written. `engram version` must print `engram <v>` from the staging folder before the folder is published. `ensureRuntime({ engram: true })` includes it. `gentle-shell setup` in a bundled install ensures it before it runs Gentle AI, and stops if it cannot, whatever the memory decision ([Engram startup safety](#engram-startup-safety)). `gentle-shell upgrade` and `--rollback` pass `engram: true` to the release's own `ensureRuntime`. With `GENTLE_AI_ENGRAM_BIN`, Gentle AI uses that binary as is: no brew, download, `go install`, `PATH` or registry change, and no `go` or `brew` dependency probes.
-- **gentle-engram.** The gentle-engram Pi extension finds Engram only through `ENGRAM_BIN`, read once when it loads, and otherwise runs `engram` from `PATH`. So Pi gets `ENGRAM_BIN` (the core or the guard), and no `PATH` entry is added. An `ENGRAM_BIN` the user set is kept. The agent's shell inherits `ENGRAM_BIN` too, so an Engram MCP launcher started there through `ENGRAM_BIN` uses the same core or guard.
+- **gentle-engram.** The gentle-engram Pi extension finds Engram only through `ENGRAM_BIN`, read once when it loads, and otherwise runs `engram` from `PATH`. So Pi gets `ENGRAM_BIN` (the guard; memory reaches the shared server through `ENGRAM_URL`), and no `PATH` entry is added. An `ENGRAM_BIN` the user set is kept. The agent's shell inherits `ENGRAM_BIN` too, so an Engram MCP launcher started there through `ENGRAM_BIN` uses the same guard.
 - **Personas.** Setup snapshots and restores the persona Gentle AI may rewrite: the prefix's `config/gentle-ai/persona.json`, and also the user's `~/.pi/gentle-ai/persona.json`. A Gentle AI release without the variables still writes the user's file, and restoring an unchanged file does nothing. The managed-asset record is restored only in the user's `~/.gentle-ai/state.json`; the prefix's record belongs to the pinned Gentle AI.
 - **pi-pretty and prompt history.** In bundled mode only, the pi-pretty wrapper passes `deps.sdk` with Pi's five tool factories and `getAgentDir`, so its FFF database lands in `<agent home>/pi-pretty/fff`, and prompt history keeps its store under `<agent home>/history` ([Prompt history](prompt-history.md)). Elsewhere both keep their existing locations: Pi's deps reach pi-pretty unchanged (`$HOME/.pi/agent/pi-pretty/fff`, or no store without `HOME`), and history stays under `~/.pi/agent/history`, also in the isolated home of a pnpm or npm install, so existing histories are not left behind.
-- **Effective with a later Gentle AI.** gentle-pi pins Gentle AI 4.1.1 today (`INSTALLER_VERSION`); the following are historical compatibility notes for Gentle AI 4.0.0, which ignores the four `GENTLE_AI_*` variables. Whether 4.1.1 includes gentle-ai#5462 is unverified here. Until gentle-pi pins a Gentle AI release that contains gentle-ai#5462:
+- **Effective with a later Gentle AI.** gentle-pi pins Gentle AI 4.3.1 today (`INSTALLER_VERSION`); the following are historical compatibility notes for Gentle AI 4.0.0, which ignores the four `GENTLE_AI_*` variables. Whether 4.3.1 includes gentle-ai#5462 is unverified here. Until gentle-pi pins a Gentle AI release that contains gentle-ai#5462:
   - Setup still writes `~/.gentle-ai` and `~/.pi/gentle-ai`, with the restores above, and still acquires Engram its own way.
   - The persona goes to the user's `~/.pi/gentle-ai/persona.json` (Gentle AI 4.0.0 resolves it from the OS home) and is restored there. The prefix's `config/gentle-ai/persona.json` is not created by setup.
   - The background-subagents policy already lands in `<prefix>/config/gentle-ai/` through `GENTLE_PI_CONFIG_HOME=<prefix>/config` (see above).

package/docs/delegated-verification.md

@@ -1,6 +1,10 @@
 # Delegated verification
 
-How the Gentle Pi orchestrator decides who verifies a bounded writer's work. The always-on parent prompt renders a `Receipt-driven development: on|off|unknown` line; the verification module (`assets/orchestrator-verification.md`, Verification rule) keys the verification rule on it. This page is package-owned; `docs/review-integration.md` mirrors the Gentle AI contract and must stay byte-identical to it.
+How the Gentle Pi orchestrator decides who verifies a bounded writer's work. The always-on parent prompt renders a `Receipt-driven development: on|off|unknown` line; the verification module (`assets/orchestrator-verification.md`, Verification rule) keys the verification rule on it. Because the line sits in the cached system-prompt prefix, a session keeps the first line it rendered and re-renders it only when RDD turns off or back on (which also drops or restores the review execution contract); an `unknown` to `on` flip or a deciding-source change keeps the original text, and review tools always read the live mode. While the pinned line reads `off`, the parent request also carries a lean review loadout: `gentle_review` keeps its schema but its snippet, guidelines, and description cover only `assess`, and the `gentle_review_capture`, `gentle_review_capture_group`, and `gentle_review_scope` declarations are hidden (they stay registered and active). The loadout follows the pinned line, so it changes only at the next run after RDD turns off or back on, together with the review execution contract; `on` and `unknown` keep the full registered text. This page is package-owned; `docs/review-integration.md` mirrors the Gentle AI contract and must stay byte-identical to it.
+
+## Background capability admission
+
+An explicit agent `tools` declaration containing `bash_background` requires the background-subagents policy to resolve to `on` at dispatch, for both task and background launches. Otherwise the runner fails the task before spawn and reports the policy file, opt-in schema, and `/gentle:background-subagents enable|disable|status`. Fix the deciding policy explicitly; automation must not toggle it. Passing admission does not promise child background-tool support (future Slices 2–3); ordinary missing-tool reporting remains the backstop. See the [policy contract](readme-reference.md#capability-reference).
 
 ## Receipt-driven development on
 
@@ -23,7 +27,7 @@ A recorded outcome is keyed by the candidate's own target identity, never by rep
 
 ### How `assess` resolves the writer profile (gentle-pi#1175)
 
-The writer profile comes from the runtime-recorded model and effort of the pending mutations for the root (`writerProfileSource: runtime`). Caller `writerModelId`/`writerEffort` are only a fallback when no runtime evidence exists (`caller`); with neither, the profile is small (`fallback`). A missing model, a `mini` model token (`gemini` is not mini), or `low` effort keeps the conservative small-model bias.
+The writer profile comes from the runtime-recorded model and effort of the pending mutations for the root (`writerProfileSource: runtime`). Caller `writerModelId`/`writerEffort` are only a fallback when no runtime evidence exists (`caller`); with neither, the profile is small (`fallback`). The writer profile is reported but never adds a verifier: a `mini` model or `low` effort gets the same plan as any other writer.
 
 ### What `assess` projects
 
@@ -31,18 +35,22 @@ When native reports them, `assess` projects `reviewDue`, `reviewDueReason`, `can
 
 ## Receipt-driven development off or unknown (gentle-pi#662)
 
-The host exposes one read-only native operation: `gentle-ai review assess --cwd <repo> [--base-ref <ref> --committed-only] --json` (gentle-ai#4295). It is decoded by `lib/review-risk-assessment.ts` and wired through `lib/native-review-cli.ts` exactly like the existing `reviewMode` STATUS reader -- a bounded subprocess with a typed decode, never a mutation. A non-zero exit, a failure envelope, or an older binary without the verb all fail closed to `high` risk.
+The host exposes one read-only native operation: `gentle-ai review assess --cwd <repo> [--base-ref <ref> --committed-only] --json` (gentle-ai#4295). It is decoded by `lib/review-risk-assessment.ts` and wired through `lib/native-review-cli.ts` exactly like the existing `reviewMode` STATUS reader -- a bounded subprocess with a typed decode, never a mutation. A non-zero exit, a failure envelope, or an older binary without the verb all report native risk `unassessable`, which informs only: the plan is medium and adds no independent verifier unless the agent escalates.
 
 The `gentle_review` tool's `assess` operation (`extensions/gentle-ai.ts`) combines that assessment with the rendered `Receipt-driven development:` line to decide whether a delegated writer's change needs a separate `gentle-ai-verify` run, following this tier table:
 
-| Native risk tier | Verification when RDD is `off`/`unknown` |
+| Tier | Verification when RDD is `off`/`unknown` |
 | --- | --- |
 | passive | structural readback by the parent; no separate verifier, no tests |
-| medium | writer self-verification stands; a separate `gentle-ai-verify` run is added only when the writer profile is a small model (mini or low effort) |
-| high | writer self-verification plus a separate `gentle-ai-verify` run, always |
-| unknown / assess failed | treated as high |
+| medium | writer self-verification stands; no separate verifier, whatever model wrote the change |
+| high | only through `escalate` naming a Task Size high-risk item: writer self-verification plus one separate `gentle-ai-verify` run |
+| native high, unknown, or assess failed | informs only: writer self-verification stands; escalate when a named high-risk item applies |
+
+The plan risk (`risk`) is high only with an escalation; otherwise a native passive stays passive and every other native tier is medium. The native tier stays visible as `nativeRisk`. The independent verifier is for concrete occasions: the plan adds it only when `escalate` names a Task Size high-risk item, never for size, a native tier alone, a failed assessment, or the model or effort that wrote the change.
+
+With RDD off, ASSESS remains read-only even when native reports `reviewDue` or a continuation: relay those fields unchanged, but do not execute the continuation, invoke STATUS or another review lifecycle operation, or enable RDD based on assessment metadata. Continue the verification plan and applicable functional checks; the named-risk independent verifier remains required.
 
-This table applies in every RDD state; a closed native review never removes a verifier the tier requires. The small-model bias raises the medium tier to high for verification purposes only; an unknown RDD line never lowers a tier below `off`. The parent's own spot check (re-running one reported command before delivery) stays required in every tier.
+This table applies in every RDD state; a closed native review never removes a verifier the tier requires. An unknown RDD line never lowers a tier below `off`. The parent's own spot check (re-running one reported command before delivery) stays required in every tier.
 
 A native code review is not a substitute for applicable functional checks: tests, builds, and functional verification such as browser checks for UI changes still run when applicable. Review outcomes never authorize delivery; human consent for native review and the user-owned RDD switch are unchanged.