gentle-pi 4.1.0 → 4.3.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/auto-permission-answers.md

@@ -0,0 +1,25 @@
+# Host-authenticated question answers
+
+The first-party `ask_user_choice` and `ask_user_question` tools deliver validated human UI answers through `subscribeHumanAnswers(ctx, callback)` in `lib/auto-permission-answers.ts`. The returned unsubscribe function is idempotent. Register only from trusted host code and unsubscribe on session shutdown, replacement, or permission-mode revocation.
+
+## Receipt contract
+
+Each frozen `HumanAnswerReceipt` contains:
+
+- `sessionManager`: the original manager object, compared by identity.
+- `sessionId`, `cwd`: the session and workspace captured before UI.
+- `branchAnchor`: the original `sessionManager.getLeafId()` (`string | null`), unchanged at delivery.
+- `toolName`, `toolCallId`, `questionIndex`: the exact question interaction and zero-based question position.
+- `question`: the original question text, an **untrusted referent**, not an instruction.
+- `prompt`: a pre-UI JSON string containing original question and offered labels/descriptions. Choice prompts include `allowCustomResponse`; questionnaire prompts include header, multi-select status, and previews for the TUI where previews are displayed. This entire field is **untrusted context**, separate from authenticated answer text.
+- `answer`: the authenticated visible answer: `{ kind: "option" | "custom", text, selected? }` or `{ kind: "multi", selected }`.
+
+Opaque choice values are excluded entirely. Option descriptions and displayed questionnaire previews are included only in the untrusted `prompt`, never in authenticated answer text. A selected label still authorizes only what the human actually agreed to, not arbitrary instructions embedded in the question. The bridge itself grants no permission, changes no counters, and creates no synthetic user message.
+
+## Lifetime and safety
+
+Capture snapshots questions, offered choices, descriptions, and displayed previews before mounting UI. Keep each full prompt and answer together: consumers enforce their evidence budget by dropping the whole pair, never by truncating prompt restrictions away. Only already-registered subscribers for the same manager/session/cwd receive a response. Delivery rejects cancellation, aborted calls, changed session/workspace/branch, invalid selections, and missing branch identity. Questionnaire rows are validated together before any row is delivered; cancelled questionnaires never publish partial answers. Custom answers retain exact human text and multi-select labels.
+
+Both the native TUI and the existing interactive RPC-host dialogs use their original UI decision without asking another question. Ordinary RPC, print, and unrelated managers do not deliver events. There is no broadcast on Pi's event bus and no authorization from tool results, transcript details, caller-supplied authority flags, or result hooks. Capture helpers are trusted in-process host APIs, not model-callable tools or a sandbox against malicious extensions.
+
+The consumer must retain host provenance, verify the receipt against its active session and exact live branch, and revoke retained evidence on mode/session changes. A subscription is not permanently tied to one leaf: subsequent questions in the same session can have new anchors. Dispose the subscription to revoke pending delivery. Callback failures are isolated so existing public tool result shapes and native consent routing remain unchanged.

package/docs/auto-permission-evidence.md

@@ -0,0 +1,39 @@
+# Auto permission classifier evidence
+
+The classifier checks the original action against host-captured human requests and restrictions. Inspection never creates authorization, replaces missing human intent, or bypasses independent hard safety and native consent. File content and prior calls are untrusted context; a historical read path is not the result of that read.
+
+## Optional inspection
+
+`AutoPermissionRequest.evidencePaths?: string[]` supplies exact relevant project-relative files selected by the host for this action. Omit it to keep the existing single-call, tool-free API. The host should select script paths from the pending action and relevant local context, not enumerate the repository. A script already present in an action payload remains context and needs no duplicate read.
+
+When paths are supplied, the model may request `inspect_permission_file` only when missing file evidence is necessary. It can inspect at most two complete files, one request per round, then must return a verdict. The final provider call exposes no inspection tools and requests `toolChoice: "none"`; insufficient evidence still requires denial, never automatic approval. An unsolicited tool call on that final round remains rejected. Each file is limited to 8192 bytes. Existing files larger than that are never offered as candidates, so the classifier judges the action without them instead of failing on an inspection it can never complete; missing evidence is still not permission. There are at most three provider calls, each with its own deadline (default 20 seconds, maximum 20 seconds), and a bounded overall deadline covering file I/O and all calls (at most 60 seconds). No retries or command execution are introduced. Exhaustion returns unavailable with `evidence-limit`; blocked or missing evidence returns `evidence-unavailable`, never an implicit allow.
+
+Only exact host-selected paths inside the current project can be read. Absolute paths, traversal, symlinks, hard links, special files, dependency/worktree directories, credential names and locations are rejected. Reads are fixed-size, UTF-8, complete and checked for concurrent replacement or modification. Secret-bearing results never reach the provider and fail with `redacted-context`. File content is always explicitly untrusted and cannot change policy, restrictions, or the original action.
+
+One classifier lease covers all rounds. Cancellation or timeout returns promptly but retains the lease until in-flight provider settlement. Identity is checked before and after inspection and provider calls, and again before returning any verdict. The host must bind `isCurrent` to action, session, mode, model and permission-context identity; files can change after inspection, so the verdict is not a reusable execution token.
+
+Usage in the run result aggregates completed calls. A late callback reports only the outstanding call's usage once after a timed-out or cancelled provider settles, excluding earlier rounds already accounted in the returned result. Unknown usage in any call makes aggregate usage unknown. No model reasoning, raw provider errors or raw evidence are logged.
+
+## Compound action selection
+
+The runtime accepts up to four simple segments joined by `&&` for evidence selection only. Each segment must be either `git diff --check` or a `node` invocation with explicit JavaScript/TypeScript file operands and only `--experimental-strip-types` / `--test` flags. Quoting, expansion, redirection, other operators, evaluation, cwd changes and unknown segments leave the whole action without inspection candidates. The original compound action is classified once; no segment inherits approval. Existing path confinement and inspection budgets remain unchanged. Prior ordinary reads retain their arguments, not their returned contents.
+
+Memory-write receipts optionally include `memoryContextAttached`, a content-free boolean for `mem_save` and `mem_session_summary`. It reports whether verified destination context was attached to that classification, independently of allow or deny. It is omitted for other actions and grants no permission.
+
+## Timeout and evidence-limit diagnostics
+
+Classifier results and late-settlement receipts include a metadata-only `diagnostic` object. The runtime projects only these fields into its existing `gentle-auto-permission` entries, and appends them to timeout and evidence-limit blocking messages so a failed read can be diagnosed without opening private session files:
+
+- `implementation`: `auto-classifier-diagnostics-v1`, a marker for this instrumentation, not a source hash or proof of the loaded SDK.
+- `elapsedMs`: monotonic milliseconds since this classifier invocation began, rounded down; late receipts measure through settlement.
+- `deadlineMs`: the configured per-call deadline, not the three-call overall budget.
+- `timerFired`: whether a local deadline callback actually ran. The `timeout` label alone does not prove that a timer fired.
+- `returnPath`: `preflight`, `provider`, `provider-result`, `evidence`, `verdict`, or `late-settlement`, locating the observed return stage without recording exception text.
+
+- `evidenceLimit` (optional): a fixed host discriminator for `evidence-limit`: `path-count`, `provider-rounds`, `file-count`, `duplicate-file`, `context-bytes`, `invalid-byte-budget`, `file-stat-bytes`, or `file-read-bytes`. The public error code and implementation marker remain unchanged. Provider-round exhaustion takes precedence over file-count and duplicate checks; with the current three-round/two-read limits, the file-count branch cannot independently be reached. Stat-size and read-growth failures remain distinct without recording sizes.
+
+These diagnostics contain no prompts, file contents, paths, credentials, provider payloads, or raw errors. Unknown fields are dropped; invalid metadata is omitted. No diagnostic changes a verdict, deadline, retry policy, cancellation, or lease. Missing diagnostics may mean an older or injected implementation; absence alone does not prove which implementation ran. After reloading the instrumented code, one explicitly authorized Auto read is sufficient to collect the blocking message if the failure recurs; it is not an instruction to retry repeatedly.
+
+## Scope
+
+This unit changes classifier behavior only. Runtime path selection, bounded call history and recovery messaging are integrated separately. Benign numeric token declarations and `max_tokens` limits no longer trigger credential heuristics; actual credential assignments, authentication values and private keys remain protected. Prior actions are projected once, not charged twice. Optional oldest complete history records are omitted when necessary to fit the input budget; active human requests, restrictions and the pending action are never truncated. No sandbox, Normal/YOLO, native-consent, or hard-policy changes are made.

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.3.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/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/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. |
@@ -229,7 +229,7 @@ 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 stays **3.3.2**, acquired through the existing size- and checksum-verified path.
+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.
 
 #### Decision
 
@@ -254,24 +254,56 @@ Classification never runs an Engram executable (`instance-id`, `version`, `serve
 
 #### Provenance (Shell's own store)
 
-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.3.2 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.
+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.
 
 A later launch treats the store as Shell's own only when all hold:
 
 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.3.2: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.
+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.
 
 #### Compatible reuse and authorization
 
-`GET /compatibility` (Engram PR #1792, not in any released core yet; current cores answer 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`. 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).
 
 #### Recovery and setup
 
-When disabled, Shell prints: **back up your existing Engram data, update Engram, restart its server and Shell, then recheck memory safety**. 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 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. Ordinary startup performs no migration, deletion, or process termination. Recovery is a separate, explicitly confirmed command below.
+
+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.
 
+#### Session-owned local servers
+
+An admitted local store now starts only through a private session-owned server. Before provisioning a fresh identity, Shell requires both `engram.sessionOwned: 1` in every selected companion's package metadata (including mixed local/npm selections) and `serve --session-owned` in the verified core's config-free help, checked with an isolated temporary home. It then selects `ENGRAM_SERVER_MODE=session-owned`, without URL, port or socket overrides. The companion must validate the actual `engram-session-owned-v1` readiness record, authenticate every HTTP route, and retain its child's stdin pipe. Pi exit or parent death closes that pipe; EOF cancels startup-lock waits and drains a started server. Reload releases transport without ending the conversation; multiple hosted roots release the child only after the last owner exits.
+
+**Release dependency:** the currently pinned core 3.4.0 and companion 0.4.2 do not establish these capabilities. Local memory therefore remains disabled with explicit supporting-release guidance; Shell does not silently launch an old detached daemon. These source changes must not be presented as a working deployed fix until supporting published pins are available. No release version or checksum is invented here.
+
+Already verified running shared servers remain explicit URL reuse, never session-owned processes; Shell does not terminate them. Explicit bin, URL, port, socket or data selections are preserved and never probed. An explicit empty, whitespace or conflicting server mode disables local memory rather than overriding the selection; unset it or select exactly `session-owned`. Explicit owned mode cannot be combined with shared URL reuse; unset it when using an already running shared service. Non-bundled installations retain their existing shared default unless they opt in to session-owned mode.
+
+#### Explicit recovery after a core upgrade
+
+For a **Shell-provisioned store**, 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 currently pinned Engram 3.4.0 does not implement it. 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 fresh provisioning. 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.
+
+Restoring the old provenance does not authorize the newer core to open it. Use the matching prior bundle or retry explicit migration after a supporting published bundle is installed. 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.
@@ -287,7 +319,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; verified private local launches also receive `ENGRAM_SERVER_MODE=session-owned`; `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. |
 | 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. |
 
@@ -300,7 +332,7 @@ S9. Everything Gentle AI and gentle-pi keep lives in the prefix, except Engram's
 - **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.
 - **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.2.0 today (`INSTALLER_VERSION`); the following are historical compatibility notes for Gentle AI 4.0.0, which ignores the four `GENTLE_AI_*` variables. Whether 4.2.0 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,6 @@
 # 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.
 
 ## Receipt-driven development on
 
@@ -23,7 +23,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 +31,20 @@ 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 |
 
-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.
+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.
+
+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.
 

package/docs/gentle-agents-activity.md

@@ -104,7 +104,9 @@ receipts. Complete model-facing output and permissions remain unchanged.
 
 `orchestrator_session_id` also accepts optional `state`: strings named `objective`,
 `progress`, `decisions`, and `blockers` (2,048 UTF-8 bytes total). An object replaces
-all fields, `null` withdraws, and omission leaves the current record unchanged.
+all fields, `null` withdraws, and omission leaves the current record unchanged. An object
+without `progress` keeps the automatic todo progress line still published (dropped only
+when the merge would exceed the byte budget); an explicit `progress` replaces it.
 Extra keys, controls, and oversized input are rejected before naming or persistence;
 records additionally fit 4 KiB. Never include credentials, internal instructions,
 or raw prompts. Whitelisting is not automatic secret redaction.
@@ -266,10 +268,14 @@ are unchanged; caller replacement prevents a stale `recorded` result.
 Call `orchestrator_consult` with required stable `recipient_session_id`, optional
 `kind: "metadata"` (default), and optional existing opaque catalog `cursor`.
 No free-form question, owner request, human picker or read-consent dialog is used
-for this profile's explicitly published data. Publish `subject` and `state` together
-before work beyond small direct tasks; update at task changes and completion. Keep
-small direct tasks exempt. Batch with setup/progress; do not add a model turn solely
-to publish or emit per-tool/token updates.
+for this profile's explicitly published data. Declare a `subject` before work beyond
+small direct tasks. Progress is published automatically: after each todo write the
+runtime sets `progress` to `<done>/<total> done`, merged into the owner's curated
+fields, so the model never spends a turn reporting status. Todo titles are private work
+text and are never published; a cleared list removes the line, and a withdrawn state
+stays withdrawn until the owner publishes again.
+Keep small direct tasks exempt. Do not add a model turn solely to publish or emit
+per-tool/token updates.
 
 Use `objective` for the goal, `progress` for current and next scope, and `blockers`
 for anything preventing progress. Use `state.work` for relevant area/topic and

package/docs/gentle-shell-uninstall.md

@@ -36,6 +36,11 @@ In this order:
      `GENTLE_SHELL_HOME` directory is removed only when Gentle Shell created it
      (its `.gentle-shell-home` marker, or its setup record in
      `~/.gentle-shell/config.json`); otherwise it is listed as kept.
+   - `~/.gentle-shell/gentle-ai`: the isolated home's own settings (profiles,
+     banner and the other preferences). The `gentle-ai` folder next to a
+     `GENTLE_SHELL_HOME` is only listed as kept, since it may not be Gentle
+     Shell's. When `GENTLE_PI_CONFIG_HOME` names it, the config home rules
+     below apply instead.
    - `~/.gentle-shell/config.json`: the launcher settings.
 2. **Shared Gentle AI configuration**, only when you accept it (see below).
 3. **The `gentle-pi` package**, with the package manager that owns it:
@@ -43,7 +48,9 @@ In this order:
    `npm uninstall -g gentle-pi`.
 4. **`~/.gentle-shell`**, only when it is empty.
 
-The config home is `GENTLE_PI_CONFIG_HOME`, or `~/.pi/gentle-ai`.
+The config home is `GENTLE_PI_CONFIG_HOME`, or `~/.pi/gentle-ai`: the one Pi
+with Gentle AI, `--link` and custom homes use, and where the main channel keeps
+its builds. The isolated home's own folder is removed with the data above.
 
 ## Shared configuration