instar 1.3.86 → 1.3.88

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-29T12:14:01.282Z",
-  "instarVersion": "1.3.86",
+  "generatedAt": "2026-05-29T13:03:58.977Z",
+  "instarVersion": "1.3.88",
   "entryCount": 193,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "8dac86cf37953d38aeda5e9d9767ac91ccb0bbaede73e879d9c4ac6efe942ab0",
+      "contentHash": "1fd1742471085a3b4ea20557d99aee966ea8bc4d92582b51cf18791ce76429d3",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "8dac86cf37953d38aeda5e9d9767ac91ccb0bbaede73e879d9c4ac6efe942ab0",
+      "contentHash": "1fd1742471085a3b4ea20557d99aee966ea8bc4d92582b51cf18791ce76429d3",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "8dac86cf37953d38aeda5e9d9767ac91ccb0bbaede73e879d9c4ac6efe942ab0",
+      "contentHash": "1fd1742471085a3b4ea20557d99aee966ea8bc4d92582b51cf18791ce76429d3",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "8dac86cf37953d38aeda5e9d9767ac91ccb0bbaede73e879d9c4ac6efe942ab0",
+      "contentHash": "1fd1742471085a3b4ea20557d99aee966ea8bc4d92582b51cf18791ce76429d3",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "8dac86cf37953d38aeda5e9d9767ac91ccb0bbaede73e879d9c4ac6efe942ab0",
+      "contentHash": "1fd1742471085a3b4ea20557d99aee966ea8bc4d92582b51cf18791ce76429d3",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "8dac86cf37953d38aeda5e9d9767ac91ccb0bbaede73e879d9c4ac6efe942ab0",
+      "contentHash": "1fd1742471085a3b4ea20557d99aee966ea8bc4d92582b51cf18791ce76429d3",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -65,7 +65,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "8dac86cf37953d38aeda5e9d9767ac91ccb0bbaede73e879d9c4ac6efe942ab0",
+      "contentHash": "1fd1742471085a3b4ea20557d99aee966ea8bc4d92582b51cf18791ce76429d3",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -74,7 +74,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "8dac86cf37953d38aeda5e9d9767ac91ccb0bbaede73e879d9c4ac6efe942ab0",
+      "contentHash": "1fd1742471085a3b4ea20557d99aee966ea8bc4d92582b51cf18791ce76429d3",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -83,7 +83,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "8dac86cf37953d38aeda5e9d9767ac91ccb0bbaede73e879d9c4ac6efe942ab0",
+      "contentHash": "1fd1742471085a3b4ea20557d99aee966ea8bc4d92582b51cf18791ce76429d3",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "8dac86cf37953d38aeda5e9d9767ac91ccb0bbaede73e879d9c4ac6efe942ab0",
+      "contentHash": "1fd1742471085a3b4ea20557d99aee966ea8bc4d92582b51cf18791ce76429d3",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -101,7 +101,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "8dac86cf37953d38aeda5e9d9767ac91ccb0bbaede73e879d9c4ac6efe942ab0",
+      "contentHash": "1fd1742471085a3b4ea20557d99aee966ea8bc4d92582b51cf18791ce76429d3",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -110,7 +110,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "8dac86cf37953d38aeda5e9d9767ac91ccb0bbaede73e879d9c4ac6efe942ab0",
+      "contentHash": "1fd1742471085a3b4ea20557d99aee966ea8bc4d92582b51cf18791ce76429d3",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "8dac86cf37953d38aeda5e9d9767ac91ccb0bbaede73e879d9c4ac6efe942ab0",
+      "contentHash": "1fd1742471085a3b4ea20557d99aee966ea8bc4d92582b51cf18791ce76429d3",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -128,7 +128,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "8dac86cf37953d38aeda5e9d9767ac91ccb0bbaede73e879d9c4ac6efe942ab0",
+      "contentHash": "1fd1742471085a3b4ea20557d99aee966ea8bc4d92582b51cf18791ce76429d3",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "8dac86cf37953d38aeda5e9d9767ac91ccb0bbaede73e879d9c4ac6efe942ab0",
+      "contentHash": "1fd1742471085a3b4ea20557d99aee966ea8bc4d92582b51cf18791ce76429d3",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1457,7 +1457,7 @@
       "type": "subsystem",
       "domain": "server",
       "sourcePath": "src/server/AgentServer.ts",
-      "contentHash": "5841418da3e9385c441f0158bc5375025dc0f39bf9ae0b4f14c2bdb7d526bf1b",
+      "contentHash": "58f8f59f8d94511835333083269d3c512e8916dede7cc69fcdaf3b159b7e392b",
       "since": "2025-01-01"
     },
     "subsystem:session-manager": {
@@ -1489,7 +1489,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "8dac86cf37953d38aeda5e9d9767ac91ccb0bbaede73e879d9c4ac6efe942ab0",
+      "contentHash": "1fd1742471085a3b4ea20557d99aee966ea8bc4d92582b51cf18791ce76429d3",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/src/scaffold/templates.ts

@@ -473,7 +473,7 @@ This routes feedback to the Instar maintainers automatically. Valid types: \`bug
 - **When to use** (PROACTIVE — this is the trigger): the moment a user offers to give you a credential (API key, password, token) or you realize you need one, use Secret Drop. It is the ONLY correct way to collect a secret. NEVER accept it pasted into Telegram or chat, and NEVER create a local file (e.g. \`.instar/secrets/foo.env\`) and ask the user to edit/paste into it — that defeats the one-time, in-memory, never-on-disk guarantee and asks the user to edit files (which you must never do). Always issue a Secret Drop one-time link instead.
 
 **Commitments & Follow-Through** — Durable tracking for any promise you make to the user. When you say "I'll report back when X", "I'll check in after N minutes", or otherwise commit to a future action, register it so the follow-through survives session turnover, restarts, and compaction.
-- Open a commitment: \`curl -X POST -H "Authorization: Bearer $AUTH" http://localhost:${port}/commitments -H 'Content-Type: application/json' -d '{"userRequest":"<what you promised>","type":"follow-up","topicId":TOPIC_ID}'\`
+- Open a one-time follow-up commitment: \`curl -X POST -H "Authorization: Bearer $AUTH" http://localhost:${port}/commitments -H 'Content-Type: application/json' -d '{"userRequest":"<what the user asked>","agentResponse":"<what you said you would do>","type":"one-time-action","topicId":TOPIC_ID}'\`
 - List / inspect: \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/commitments\` · \`GET /commitments/:id\`
 - Mark delivered when done: \`curl -X POST -H "Authorization: Bearer $AUTH" http://localhost:${port}/commitments/:id/deliver\`
 - The PromiseBeacon fires cadenced heartbeats on open commitments so you actually follow through (and surfaces atRisk items), and the commitment-check job surfaces overdue ones.

package/upgrades/0.9.15.md

@@ -10,7 +10,7 @@ Now every MCP tool call passes through a safety gate:
 
 1. **PreToolUse Hook** (`external-operation-gate.js`): Automatically installed in `.instar/hooks/`. Intercepts all `mcp__*` tool calls, classifies them by mutability (read/write/modify/delete) and reversibility, then calls the gate API.
 
-2. **ExternalOperationGate**: Server-side risk evaluation. Combines the operation classification with a risk matrix to decide: `allow`, `block`, `show-plan` (requires user approval), or `suggest-alternative`. Dangerous operations (bulk deletes, irreversible sends) require explicit user approval.
+2. **ExternalOperationGate**: Server-side risk evaluation. Combines the operation classification with a risk matrix to decide: `proceed`, `block`, `show-plan` (requires user approval), or `suggest-alternative`. Dangerous operations (bulk deletes, irreversible sends) require explicit user approval.
 
 3. **MessageSentinel**: Emergency stop detection. If the user says "stop everything" or "emergency stop", the sentinel intercepts the message and halts operations immediately — before normal message routing.
 

package/upgrades/1.3.85.md

@@ -4,27 +4,27 @@
 
 ## What Changed
 
-The Coherence Gate now represents unbound topic-project alignment as an
-indeterminate check and summarizes the result honestly. A warning-level
-indeterminate check is no longer counted as passed in the top-level pass flag or
-the human-readable summary. Recommendation behavior is unchanged: clean checks
-proceed, warning-level checks warn, and error-level checks block.
+The External Operation Gate action vocabulary is now consistent across the
+endpoint, generated hook, generated guidance, and docs. The canonical successful
+action is `proceed`; `allow` is retained only as a legacy hook compatibility
+alias. Unknown action values from the gate now block external write/delete MCP
+operations instead of being permitted through fallthrough.
 
 ## What to Tell Your User
 
-- **Coherence checks are clearer**: "When I verify a risky action, I'll now tell you when a check needs human verification instead of incorrectly saying every check passed."
+- **External operation safety is clearer**: "When I gate an external-service action, the documented decision words now match the live evaluator. Allowed operations say proceed, risky ones ask for a plan, and malformed gate responses stop instead of slipping through."
 
 ## Summary of New Capabilities
 
 | Capability | How to Use |
 |-----------|-----------|
-| Honest indeterminate Coherence Gate summaries | Automatic for pre-action coherence checks |
+| External Operation Gate vocabulary alignment | Automatic for generated hooks and evaluator responses |
 
 ## Evidence
 
-Before the change, a live Coherence Gate request for an unbound topic returned a
-warning recommendation while the summary still said all four coherence checks
-passed. After the change, focused unit, HTTP route, and e2e lifecycle tests
-verify that the unbound topic check returns an indeterminate value, the overall
-pass flag is false, the recommendation remains warn, and the summary includes
-the indeterminate count instead of the all-passed sentence.
+Before the change, live evaluation returned `proceed` while generated docs
+described the allowed action as `allow`, and the hook accepted `proceed` only by
+falling through unrecognized actions. After the change, focused unit tests cover
+core vocabulary and hook behavior, integration tests cover representative
+evaluator route outcomes, and an e2e HTTP lifecycle verifies `proceed`,
+`show-plan`, and `block` outcomes through AgentServer.

package/upgrades/1.3.87.md

@@ -0,0 +1,30 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+Two fixes ship together here.
+
+**Operation-safety gate action vocabulary and fail-closed hardening.** The external operation-safety gate emits a proceed action for allowed operations, but the generated guard hook and the docs described the allowed action as allow and only branched explicitly on the block, show-plan, and suggest-alternative cases — so proceed was permitted only by falling through, and an unrecognized action would slip through that same silent path. The hook now permits proceed explicitly (keeping allow for backward compatibility) and blocks any unrecognized action instead of letting it pass, and the docs and generated guidance now use the real vocabulary. This is a safety tightening: an unknown gate decision now fails closed.
+
+**Commitments follow-up contract guidance.** The generated Commitments guidance described creating follow-up promises with a type the server actually rejects and omitted a required field. Agents now record follow-up promises as one-time-action commitments that include both the user request and the agent response before marking them delivered, matching the live contract.
+
+## What to Tell Your User
+
+- **The operation-safety gate is stricter now**: when I check whether an outside action is safe, an allowed action is now handled on purpose rather than by accident, and anything the safety check does not recognize is blocked rather than waved through. How existing approvals and blocks work is unchanged.
+- **Commitment follow-through is more reliable**: when I register a future follow-up for myself, the built-in guidance now uses the same wording the server actually accepts, so the reminder can be created and closed cleanly.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Operation-gate fail-closed on unknown actions | Automatic. The generated operation-safety hook now blocks any unrecognized gate decision instead of permitting it, and treats the allowed action explicitly. |
+| Operation-gate vocabulary alignment | Automatic. Docs and generated guidance now match the action values the gate actually emits. |
+| Commitments follow-up contract guidance | Automatic for newly generated or migrated agent guidance. |
+
+## Evidence
+
+- Operation gate: unit (ExternalOperationGate and hook-installation), integration (operation-safety routes), and e2e (action-vocabulary lifecycle) tests cover the explicit-permit, legacy-compat, and block-unknown paths; the docs, templates, and spec were aligned to the real vocabulary.
+- Commitments: live lifecycle verification created a test commitment, inspected it, delivered it, and verified it was terminal and closed; focused unit, integration, and e2e tests pin the accepted create payload, delivery transition, active-list closure, generated guidance, and PromiseBeacon stop behavior.
+- Note: the operation-gate change merged to main first, but its release notes were dropped during a rebase across a release-cut, so it is released here alongside the commitments guidance fix.

package/upgrades/1.3.88.md

@@ -0,0 +1,30 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+Mentor onboarding now hot-reads the mentor settings from the agent config file
+each time the runner checks its configuration. Updating the mentor curriculum or
+mentor runtime settings no longer requires a full server restart. If the config
+file is missing, unreadable, malformed, or has a malformed mentor block, the
+runner falls back to the startup snapshot instead of throwing into a mentor tick.
+
+## What to Tell Your User
+
+- **Mentor settings update without a restart**: "When you adjust the mentor curriculum or related mentor settings, the running server picks them up on the next mentor check. If the config edit is malformed, the mentor keeps using its last safe startup settings instead of failing a tick."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|------------|
+| Mentor config hot-read | Edit mentor settings in the agent config file; the next mentor status check or tick reads the updated mentor block |
+| Defensive mentor config fallback | Malformed config edits keep the mentor on its startup settings until the file is repaired |
+
+## Evidence
+
+Unit coverage proves changed on-disk mentor agendas are read on the next call
+and malformed config falls back to the startup snapshot. Integration coverage
+pins the mentor route to fresh runner config reads. Server-backed e2e coverage
+proves a running AgentServer reflects mentor config edits without restart and
+falls back safely when the config file is malformed.

package/upgrades/side-effects/commitments-agent-contract-vocabulary.md

@@ -0,0 +1,39 @@
+# Commitments Agent Contract Vocabulary
+
+## Scope
+
+Align generated agent guidance with the live `/commitments` API contract for one-time follow-up promises.
+
+## Runtime Finding
+
+Live verification showed the lifecycle works with the actual contract:
+
+1. Create with `type:"one-time-action"`, `userRequest`, `agentResponse`, and `topicId` returns a `pending` commitment with the expected fields.
+2. Direct lookup returns the same record.
+3. Delivery transitions the commitment to `delivered`, sets `resolvedAt`, increments the version, and closes it from active follow-up.
+4. PromiseBeacon delivery behavior is already covered by integration: delivered commitments stop scheduled beacon work and later fires are no-ops.
+
+The rejected shape was the generated guidance: `type:"follow-up"` plus no `agentResponse`.
+
+## Files
+
+- `src/scaffold/templates.ts` — update new-agent Commitments guidance to use `one-time-action` and include `agentResponse`.
+- `src/core/PostUpdateMigrator.ts` — update migrated Commitments guidance for existing agents.
+- `src/data/builtin-manifest.json` — regenerated after template guidance changes.
+- `tests/unit/PostUpdateMigrator-secretDropHardenedRetrieve.test.ts` — pin migrated guidance vocabulary.
+- `tests/unit/commitments-agent-guidance-contract.test.ts` — pin template and migrator vocabulary together.
+- `tests/unit/commitment-routes.test.ts` — cover the agent-facing create shape and deliver transition.
+- `tests/e2e/commitments-api-lifecycle.test.ts` — cover create, lookup, deliver, lookup, and active-list closure through HTTP.
+- `docs/specs/COMMITMENTS-AGENT-CONTRACT-VOCABULARY-SPEC.md` — durable contract note.
+- `docs/specs/COMMITMENTS-AGENT-CONTRACT-VOCABULARY-SPEC.eli16.md` — plain-language overview.
+- `upgrades/NEXT.md` — release-note entry for the next patch.
+
+## Side Effects
+
+Existing agents that receive migrated guidance will be taught the accepted route contract. Existing commitment records are not migrated and no stored status vocabulary changes.
+
+The guidance still uses "open" as a human verb. The API status for a newly created one-time follow-up remains `pending`.
+
+## Rollback
+
+Revert the template/migrator and tests. Runtime commitment behavior is unchanged by this PR.

package/upgrades/side-effects/external-operation-action-vocabulary.md

@@ -0,0 +1,132 @@
+---
+title: External Operation Gate — action vocabulary alignment
+slug: external-operation-action-vocabulary
+date: 2026-05-29
+author: codey
+second_pass_required: false
+---
+
+## Summary of the change
+
+The External Operation Gate endpoint already used `proceed` as its canonical
+allowed action, but generated documentation described the action as `allow`, and
+the generated PreToolUse hook accepted `proceed` only through an implicit
+fallthrough path. This change aligns the docs and hook with the core gate:
+`proceed`, `show-plan`, `suggest-alternative`, and `block`. The hook explicitly
+permits `proceed`, keeps legacy `allow` compatibility, and blocks unknown action
+values instead of silently proceeding.
+
+Files touched include the hook generator in `PostUpdateMigrator`, generated and
+source documentation, capability text, and unit/integration/e2e tests.
+
+## Decision-point inventory
+
+- `ExternalOperationGate.evaluate()` — pass-through — remains the authority and
+  source of truth for emitted action values.
+- Generated `external-operation-gate.js` hook — modified — explicitly maps
+  `proceed` and legacy `allow` to permit; unknown actions now block.
+- Generated/documented External Operation Safety guidance — modified — names
+  `proceed` instead of `allow`.
+
+---
+
+## 1. Over-block
+
+The new over-block risk is a gate response with a valid future action value that
+this hook version does not recognize. The hook would block it. That is
+intentional for this trust boundary: new action values must be added to the hook
+and tests deliberately, rather than inheriting permission through fallthrough.
+
+Legacy `allow` is accepted to avoid over-blocking stale local test doubles or
+older endpoints during mixed-version windows.
+
+---
+
+## 2. Under-block
+
+The main previous under-block was unknown action fallthrough. That is removed.
+The remaining under-block is the existing designed fail-open path when the local
+server is unreachable or the hook cannot parse input. This change does not alter
+that broader availability policy.
+
+---
+
+## 3. Level-of-abstraction fit
+
+The endpoint remains the authority for operation risk. The hook is the local
+enforcement adapter that translates action words into command behavior. Keeping
+legacy compatibility at the hook boundary is the right layer because it protects
+mixed-version local installs without changing the core gate's canonical type.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change does not add a brittle detector with blocking authority.
+
+The hook is already an enforcement authority at an external-service trust
+boundary. This change narrows that authority's accepted action vocabulary to the
+canonical gate contract, plus one explicit legacy alias. It does not introduce a
+new heuristic signal.
+
+---
+
+## 5. Interactions
+
+- **Hook install/migration:** existing installations receive the updated hook
+  when the post-update migrator refreshes built-in hook content.
+- **Mixed versions:** a hook updated before an endpoint still accepts legacy
+  `allow`; an endpoint updated before a hook already worked because old hooks
+  fell through on `proceed`.
+- **Identity grounding:** irreversible writes that receive `proceed` still pass
+  through the existing identity-grounding injection path before allowing the
+  operation.
+- **Read fast path:** read MCP calls still exit locally before calling the gate.
+
+---
+
+## 6. External surfaces
+
+External-service MCP calls are affected. The successful endpoint action is
+documented as `proceed`; callers that asserted the old documentation should
+update. The hook's runtime behavior is stricter for malformed gate responses:
+unknown actions now block non-read external operations instead of silently
+running them.
+
+No persistent state schema changes, no database migrations, and no external API
+credentials are affected.
+
+---
+
+## 7. Rollback cost
+
+Pure code and docs rollback. Revert the hook generator and docs/tests; no data
+cleanup is needed. During rollback, `proceed` would again be permitted only by
+unknown fallthrough in the hook, which is the behavior this change removes.
+
+---
+
+## Conclusion
+
+The mismatch is reconciled by treating the core gate as authoritative and
+pinning `proceed` as the canonical allowed action. The compatibility alias keeps
+mixed-version behavior stable, while the unknown-action block removes the
+silent-fallthrough safety gap. Clear to ship.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** not required
+**Independent read of the artifact:** not required
+
+---
+
+## Evidence pointers
+
+- `tests/unit/ExternalOperationGate.test.ts`
+- `tests/unit/hook-installation.test.ts`
+- `tests/integration/external-operation-safety-routes.test.ts`
+- `tests/e2e/external-operation-action-vocabulary-lifecycle.test.ts`

package/upgrades/side-effects/mentor-config-hot-read.md

@@ -0,0 +1,103 @@
+# Side-Effects Review — Mentor config hot-read
+
+**Version / slug:** `mentor-config-hot-read`
+**Date:** `2026-05-29`
+**Author:** `instar-codey`
+**Second-pass reviewer:** `instar-codey second-pass checklist`
+
+## Summary of the change
+
+This change makes the mentor runner read the mentor block from the agent config
+file each time it needs configuration. The startup mentor config is retained as
+the fallback for missing, unreadable, or malformed config reads. This lets
+operators adjust the mentor curriculum and runtime settings without restarting
+the server while keeping mentor ticks defensive.
+
+## Decision-point inventory
+
+- `readMentorConfigFromDisk` — add — reads and merges the current on-disk mentor
+  block with defaults, or returns the startup fallback on unsafe reads.
+- `AgentServer.buildMentorRunner` — modify — passes a fresh-reading getConfig
+  closure to the mentor runner instead of closing over startup config.
+- Mentor route and e2e tests — modify — pin route-level and server-level hot-read
+  behavior.
+
+---
+
+## 1. Over-block
+
+A malformed mentor block now falls back to the startup snapshot rather than
+partially applying valid fields around the malformed value. That is intentional:
+the config edit is not trustworthy enough to merge safely, and keeping the last
+known startup behavior is less surprising than accepting a half-bad shape.
+
+## 2. Under-block
+
+The helper performs only shallow shape validation, matching the previous runtime
+behavior that trusted the loaded config shape. Invalid field values inside an
+object can still flow through. This PR does not add schema validation because the
+request was scoped to hot-reading and defensive read failures, not changing the
+mentor config contract.
+
+## 3. Level-of-abstraction fit
+
+The hot-read belongs at the `AgentServer` runner boundary, where the server
+already wires state directory access into the mentor runner. The runner remains a
+pure dependency-injected orchestrator and still receives a simple getConfig
+function.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [ ] No — this change produces a signal consumed by an existing smart gate.
+- [ ] No — this change has no block/allow surface.
+- [ ] Yes — but the logic is a smart gate with full conversational context.
+- [x] Not applicable to conversational/product judgment — this is runtime config
+  loading for a dormant/off-by-default mentor job.
+
+## 5. Interactions
+
+- **Shadowing:** The helper reads only the mentor block and does not mutate the
+  main server config object.
+- **Double-fire:** No new timers or routes are introduced; existing mentor status
+  and tick calls simply observe fresher config.
+- **Races:** A config write racing with a mentor tick can produce a transient
+  parse failure. The fallback path handles that by using the startup snapshot.
+- **Feedback loops:** Live mentor delivery can now observe changed topic or
+  curriculum settings without restart. Outstanding-prompt safeguards remain
+  unchanged.
+
+## 6. External surfaces
+
+Operators can update mentor settings while the server is running. A bad edit no
+longer risks throwing through a mentor tick. No public API shape changes, data
+migrations, Telegram topic creation, or dashboard changes are introduced.
+
+## 7. Rollback cost
+
+Rollback is a code and test revert. No persisted data is migrated or rewritten.
+
+## Conclusion
+
+The change addresses the stale mentor config cache directly and keeps the mentor
+loop defensive under malformed runtime config edits. Unit, integration, and e2e
+tests cover the hot-read and fallback behavior.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** instar-codey second-pass checklist
+**Independent read of the artifact:** concur
+
+The second pass agrees that the helper is scoped to mentor config only, preserves
+the runner abstraction, and does not introduce new authority or delivery paths.
+
+---
+
+## Evidence pointers
+
+- `tests/unit/AgentServer-mentor-config-hot-read.test.ts`
+- `tests/integration/mentor-routes.test.ts`
+- `tests/e2e/mentor-onboarding-lifecycle.test.ts`