@iflow-mcp/jkheadley-instar 0.26.2

package/src/templates/scripts/telegram-reply.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+# telegram-reply.sh — Send a message back to a Telegram topic via instar server.
+#
+# Usage:
+#   ./telegram-reply.sh TOPIC_ID "message text"
+#   echo "message text" | ./telegram-reply.sh TOPIC_ID
+#   cat <<'EOF' | ./telegram-reply.sh TOPIC_ID
+#   Multi-line message here
+#   EOF
+#
+# Reads INSTAR_PORT from environment (default: 4040).
+
+TOPIC_ID="$1"
+shift
+
+if [ -z "$TOPIC_ID" ]; then
+  echo "Usage: telegram-reply.sh TOPIC_ID [message]" >&2
+  exit 1
+fi
+
+# Read message from args or stdin
+if [ $# -gt 0 ]; then
+  MSG="$*"
+else
+  MSG="$(cat)"
+fi
+
+if [ -z "$MSG" ]; then
+  echo "No message provided" >&2
+  exit 1
+fi
+
+PORT="${INSTAR_PORT:-4040}"
+
+# Read auth token from config (if present)
+AUTH_TOKEN=""
+if [ -f ".instar/config.json" ]; then
+  AUTH_TOKEN=$(python3 -c "import json; print(json.load(open('.instar/config.json')).get('authToken',''))" 2>/dev/null)
+fi
+
+# Escape for JSON
+JSON_MSG=$(printf '%s' "$MSG" | python3 -c 'import sys,json; print(json.dumps(sys.stdin.read()))' 2>/dev/null)
+if [ -z "$JSON_MSG" ]; then
+  # Fallback if python3 not available: basic escape
+  JSON_MSG="\"$(printf '%s' "$MSG" | sed 's/\\/\\\\/g; s/"/\\"/g; s/\n/\\n/g')\""
+fi
+
+if [ -n "$AUTH_TOKEN" ]; then
+  RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "http://localhost:${PORT}/telegram/reply/${TOPIC_ID}" \
+    -H 'Content-Type: application/json' \
+    -H "Authorization: Bearer ${AUTH_TOKEN}" \
+    -d "{\"text\":${JSON_MSG}}")
+else
+  RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "http://localhost:${PORT}/telegram/reply/${TOPIC_ID}" \
+    -H 'Content-Type: application/json' \
+    -d "{\"text\":${JSON_MSG}}")
+fi
+
+HTTP_CODE=$(echo "$RESPONSE" | tail -1)
+BODY=$(echo "$RESPONSE" | sed '$d')
+
+if [ "$HTTP_CODE" = "200" ]; then
+  echo "Sent $(echo "$MSG" | wc -c | tr -d ' ') chars to topic $TOPIC_ID"
+else
+  echo "Failed (HTTP $HTTP_CODE): $BODY" >&2
+  exit 1
+fi

package/src/templates/scripts/whatsapp-reply.sh

@@ -0,0 +1,68 @@
+#!/bin/bash
+# whatsapp-reply.sh — Send a message back to a WhatsApp JID via instar server.
+#
+# Usage:
+#   ./whatsapp-reply.sh JID "message text"
+#   echo "message text" | ./whatsapp-reply.sh JID
+#   cat <<'EOF' | ./whatsapp-reply.sh JID
+#   Multi-line message here
+#   EOF
+#
+# JID format: phone@s.whatsapp.net (e.g., 12345678901@s.whatsapp.net)
+# Reads INSTAR_PORT from environment (default: 4040).
+
+JID="$1"
+shift
+
+if [ -z "$JID" ]; then
+  echo "Usage: whatsapp-reply.sh JID [message]" >&2
+  exit 1
+fi
+
+# Read message from args or stdin
+if [ $# -gt 0 ]; then
+  MSG="$*"
+else
+  MSG="$(cat)"
+fi
+
+if [ -z "$MSG" ]; then
+  echo "No message provided" >&2
+  exit 1
+fi
+
+PORT="${INSTAR_PORT:-4040}"
+
+# Read auth token from config (if present)
+AUTH_TOKEN=""
+if [ -f ".instar/config.json" ]; then
+  AUTH_TOKEN=$(python3 -c "import json; print(json.load(open('.instar/config.json')).get('authToken',''))" 2>/dev/null)
+fi
+
+# Escape for JSON
+JSON_MSG=$(printf '%s' "$MSG" | python3 -c 'import sys,json; print(json.dumps(sys.stdin.read()))' 2>/dev/null)
+if [ -z "$JSON_MSG" ]; then
+  # Fallback if python3 not available: basic escape
+  JSON_MSG="\"$(printf '%s' "$MSG" | sed 's/\\/\\\\/g; s/"/\\"/g; s/\n/\\n/g')\""
+fi
+
+if [ -n "$AUTH_TOKEN" ]; then
+  RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "http://localhost:${PORT}/whatsapp/send/${JID}" \
+    -H 'Content-Type: application/json' \
+    -H "Authorization: Bearer ${AUTH_TOKEN}" \
+    -d "{\"text\":${JSON_MSG}}")
+else
+  RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "http://localhost:${PORT}/whatsapp/send/${JID}" \
+    -H 'Content-Type: application/json' \
+    -d "{\"text\":${JSON_MSG}}")
+fi
+
+HTTP_CODE=$(echo "$RESPONSE" | tail -1)
+BODY=$(echo "$RESPONSE" | sed '$d')
+
+if [ "$HTTP_CODE" = "200" ]; then
+  echo "Sent $(echo "$MSG" | wc -c | tr -d ' ') chars to $JID"
+else
+  echo "Failed (HTTP $HTTP_CODE): $BODY" >&2
+  exit 1
+fi

package/upgrades/0.10.0.md

@@ -0,0 +1,254 @@
+# Upgrade Guide — v0.10.0
+
+<!-- bump: minor -->
+
+## What Changed
+
+### Working Memory Assembly — Right Context at the Right Moment
+
+Your agent now assembles working memory at session start and after compaction. Instead of loading everything or nothing, the system queries your knowledge stores for what's most relevant to the current task and injects it automatically.
+
+**What this means for you:**
+- Session starts with contextually relevant knowledge surfaced from SemanticMemory
+- Recent episode digests (what you worked on in the last 48 hours) appear automatically
+- Person/relationship entities relevant to the current task are included
+- Compaction recovery now also restores relevant working memory — not just identity
+
+**How it works:**
+1. The session-start hook calls `GET /context/working-memory?prompt=<session-goal>`
+2. WorkingMemoryAssembler queries SemanticMemory, EpisodicMemory, and TopicMemory
+3. Results are token-budgeted (800 tokens knowledge + 400 episodes + 300 relationships + 300 topic)
+4. Top 3 entities get full detail, next 7 get compact, rest are name-only
+5. Formatted context is injected before any work begins
+
+**New API endpoint:** `GET /context/working-memory?prompt=<query>&topicId=<id>&sessionId=<id>&limit=<n>`
+
+No configuration required — it works automatically if SemanticMemory or EpisodicMemory is enabled.
+
+---
+
+### Inter-Agent Messaging — Structured Communication Between Sessions
+
+Previously, Instar sessions running on the same machine had no way to communicate with each other. If session A discovered something session B needed to know, or if a job wanted to notify a running session about an important event, the only option was writing to a shared file and hoping the other session noticed. There was no delivery tracking, no acknowledgment, no threading, and no way to know if the message was ever received.
+
+Now Instar includes a full **Inter-Agent Messaging** subsystem — structured message passing between sessions with delivery tracking, safe tmux injection, and a complete API.
+
+### How It Works
+
+Messages flow through four layers:
+
+1. **MessageRouter** — The primary entry point. Handles sending, receiving, acknowledging, and relaying messages. Enforces echo prevention (can't message yourself), loop detection on relay chains, and deduplication.
+
+2. **MessageStore** — File-based persistence. Each message is stored as a single JSON file in `.instar/messages/store/`. Supports inbox/outbox queries, filtering by type/priority, dead-letter queue for expired messages, and cleanup of old data.
+
+3. **MessageDelivery** — Safe tmux injection. Before injecting a message into a session's terminal, it checks:
+   - Is the foreground process on the whitelist? (bash, zsh, fish, sh, dash, claude)
+   - Is a human actively typing? (won't interrupt human input)
+   - Is there enough terminal context budget? (won't flood a small terminal)
+
+4. **MessageFormatter** — Formats messages for terminal display (inline mode for short messages, pointer mode for long ones) with delimiter sanitization to prevent injection attacks.
+
+### Message Types
+
+Nine message types, each with default TTL and retention:
+
+| Type | Purpose | Default TTL |
+|------|---------|-------------|
+| `info` | Informational — no response expected | 60 min |
+| `sync` | State synchronization | 30 min |
+| `alert` | Urgent notification | 120 min |
+| `request` | Action request — please do something | 120 min |
+| `query` | Question — please respond with information | 60 min |
+| `response` | Answer to a query | 60 min |
+| `handoff` | Session/machine handoff context | 240 min |
+| `wellness` | Health check ping | 15 min |
+| `system` | Infrastructure message from the Instar server | 30 min |
+
+### 4-Phase Delivery Tracking
+
+Every message transitions through delivery phases with full audit trail:
+
+```
+created → sent → received → delivered → read
+                         ↘ queued ↗
+```
+
+Each transition is recorded with timestamp and reason. Transitions are **monotonic** — a message can never go backward (with one exception: `delivered → queued` for post-injection crash recovery by the watchdog).
+
+Messages that aren't delivered in time follow the expiration path: `expired → dead-lettered`.
+
+### Threading
+
+Query and request messages automatically create threads. Responses link back via `inReplyTo`. Threads track participants and have depth limits (50) and staleness timeouts (30 min).
+
+### Relay Support
+
+Messages can be relayed between agents on the same machine (`/messages/relay-agent`) or across machines (`/messages/relay-machine`). The relay chain tracks which machines have seen the message to prevent loops. Duplicate messages are detected and acknowledged without re-storing.
+
+## API Endpoints (For Your Use)
+
+These endpoints are available on the Instar server:
+
+| Endpoint | Method | What It Does |
+|----------|--------|-------------|
+| `/messages/send` | POST | Send a message to another agent/session |
+| `/messages/ack` | POST | Acknowledge receipt of a message |
+| `/messages/relay-agent` | POST | Receive a relayed message from another agent on the same machine |
+| `/messages/relay-machine` | POST | Receive a relayed message from a different machine |
+| `/messages/stats` | GET | Messaging statistics (volume, delivery rates, threads) |
+
+All endpoints require your standard Bearer token authentication. When messaging isn't wired in, all endpoints return 503.
+
+### Sending a Message
+
+```
+POST /messages/send
+{
+  "from": { "agent": "my-agent", "session": "session-1", "machine": "my-machine" },
+  "to": { "agent": "other-agent", "session": "their-session", "machine": "local" },
+  "type": "query",
+  "priority": "medium",
+  "subject": "What's your current task?",
+  "body": "I'm about to work on the auth module — want to check we're not overlapping."
+}
+```
+
+Response: `201 Created` with `{ messageId, threadId, phase: "sent" }`.
+
+### Acknowledging a Message
+
+```
+POST /messages/ack
+{
+  "messageId": "uuid-of-the-message",
+  "sessionId": "my-session-id"
+}
+```
+
+Response: `200 OK` with `{ ok: true }`.
+
+## Wiring Into Your Server
+
+If you're using `AgentServer` programmatically, pass the messaging dependencies:
+
+```typescript
+import { MessageStore, MessageFormatter, MessageDelivery, MessageRouter, AgentServer } from 'instar';
+
+const messageStore = new MessageStore(path.join(stateDir, 'messages'));
+await messageStore.initialize();
+
+const formatter = new MessageFormatter();
+const delivery = new MessageDelivery(formatter, tmuxOps);
+const messageRouter = new MessageRouter(messageStore, delivery, {
+  localAgent: 'my-agent',
+  localMachine: 'my-machine',
+  serverUrl: 'http://localhost:3000',
+});
+
+const server = new AgentServer({
+  config,
+  sessionManager,
+  state,
+  messageRouter, // ← enables all /messages/* endpoints
+});
+```
+
+Without `messageRouter`, all messaging endpoints gracefully return 503 — the server still works, messaging just isn't available.
+
+## Type Export Note
+
+The new messaging types `MessageType` and `AgentMessage` are exported as `InterAgentMessageType` and `InterAgentMessage` from the top-level `instar` package to avoid naming conflicts with the existing `AgentBus` exports. If you prefer the unaliased names, import directly:
+
+```typescript
+import type { MessageType, AgentMessage } from 'instar/messaging/types';
+```
+
+---
+
+### Hybrid Search — Semantic + Keyword Search Combined
+
+SemanticMemory now supports hybrid search that combines BM25 keyword matching with vector similarity. When you search your knowledge, both approaches run simultaneously, and results are fused using Reciprocal Rank Fusion (RRF) for the best of both worlds.
+
+**What this means for you:**
+- Exact keyword matches (API names, error codes, specific terms) are found reliably
+- Conceptual/semantic matches still work for broader queries
+- Results are better than either approach alone — keyword handles precision, vectors handle recall
+
+**How it works:**
+1. `POST /semantic/search` now runs both keyword (BM25) and vector search in parallel
+2. Results are fused using RRF with configurable weights (`alpha` parameter: 0.0 = pure keyword, 1.0 = pure vector, 0.5 = balanced)
+3. FTS5 index is automatically created and maintained alongside the existing vector index
+4. Full-text index stays synchronized via automatic triggers on entity create/update/delete
+
+**New search parameters:**
+- `alpha` (0.0-1.0, default 0.5) — Balance between keyword and vector search
+- `mode` ("hybrid" | "keyword" | "vector", default "hybrid") — Choose search strategy
+- All existing search parameters (`limit`, `domain`, `type`, `minConfidence`, `tags`) still work
+
+**New API endpoints:**
+- `GET /semantic/search-stats` — Search statistics (FTS index size, entity count, index health)
+
+The FTS5 index is populated automatically from existing entities on first use. No migration needed — the index builds itself.
+
+---
+
+### MEMORY.md Generation — Export Your Knowledge as Markdown
+
+SemanticMemory can now export its entire knowledge base as a structured MEMORY.md file. This replaces the legacy MemoryIndex-based approach with a richer, domain-grouped format generated directly from your knowledge graph.
+
+**What this means for you:**
+- Your MEMORY.md reflects your actual semantic knowledge, not a flat key-value dump
+- Entities are grouped by domain (Infrastructure, Development, Relationships, etc.) then by type
+- Confidence scores are visible — you can see what you're most/least sure about
+- Low-confidence entities are automatically filtered out (below 0.2 threshold)
+- A footer shows entity count, domain count, and generation timestamp
+
+**How it works:**
+1. `POST /semantic/export-memory` generates markdown from all active SemanticMemory entities
+2. Entities are grouped by domain, then by type (projects before people before tools, etc.)
+3. Each entity includes its content, confidence indicator, and tags
+4. Optional `filePath` parameter writes directly to disk (creates parent dirs automatically)
+5. Optional `agentName` parameter customizes the header (default: "Agent")
+
+**New API endpoint:** `POST /semantic/export-memory`
+- Request body: `{ filePath?, minConfidence?, maxEntities?, agentName?, includeFooter? }`
+- Response: `{ markdown, entityCount, excludedCount, domainCount, filePath? }`
+
+**New CLI command:** `instar memory export`
+- `instar memory export` — print to stdout
+- `instar memory export -o MEMORY.md` — write to file
+- `instar memory export -a Dawn --min-confidence 0.5` — custom agent name, higher confidence threshold
+
+**Legacy deprecation:** The old `/memory/*` endpoints (MemoryIndex-based) now return `Deprecation` and `Sunset` HTTP headers. They continue to work but will be removed in v1.0. Migrate to SemanticMemory + `/semantic/export-memory` for the full knowledge graph experience.
+
+## What to Tell Your User
+
+- **Your sessions now start smarter**: "I assemble relevant context automatically at session start — recent work, key relationships, relevant knowledge. No more cold starts."
+- **Sessions can talk to each other**: "My sessions can now send structured messages to each other — queries, status updates, handoff context. If I'm running multiple tasks, they coordinate instead of working blind."
+- **Delivery tracking**: "Every message has delivery tracking. I know whether a message was sent, received, delivered to the terminal, and read. Nothing gets silently lost."
+- **Safe injection**: "Messages are injected into terminals safely — they won't interrupt you if you're typing, and they only inject when the session is in a safe state."
+- **Foundation for coordination**: "This is the communication layer that enables future multi-agent coordination — task delegation, conflict avoidance, and handoff between sessions."
+- **Better search**: "When I search my memory, I now use both exact keyword matching and semantic similarity together. This means I find things more reliably — whether you give me a specific term or describe the concept."
+- **Richer memory snapshots**: "My MEMORY.md is now generated from my full knowledge graph, organized by domain and type. It's a much more accurate reflection of what I actually know."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Working memory assembly | Automatic at session start via `GET /context/working-memory` |
+| Send messages between sessions | `POST /messages/send` with from, to, type, priority, subject, body |
+| Acknowledge message receipt | `POST /messages/ack` with messageId and sessionId |
+| Relay messages between agents | `POST /messages/relay-agent` with full message envelope |
+| Cross-machine relay | `POST /messages/relay-machine` with full message envelope |
+| View messaging stats | `GET /messages/stats` — volume, delivery rates, thread counts |
+| 9 message types | info, sync, alert, request, query, response, handoff, wellness, system |
+| Automatic threading | Query and request messages auto-create threads |
+| Delivery tracking | 4-phase: sent → received → delivered → read |
+| Dead-letter queue | Expired/failed messages preserved for debugging |
+| Safe tmux injection | Process whitelist, human-input detection, context budget |
+| File-based persistence | Per-message JSON in `.instar/messages/store/` |
+| Hybrid search (keyword + vector) | `POST /semantic/search` with `alpha` and `mode` parameters |
+| Search statistics | `GET /semantic/search-stats` — FTS index health, entity count |
+| Export knowledge as MEMORY.md | `POST /semantic/export-memory` or `instar memory export` |
+| Custom export options | `minConfidence`, `maxEntities`, `agentName`, `filePath` |
+| Legacy endpoint deprecation | `/memory/*` routes return Deprecation/Sunset headers |

package/upgrades/0.10.1.md

@@ -0,0 +1,47 @@
+# Upgrade Guide — v0.10.1
+
+<!-- bump: minor -->
+<!-- Valid values: patch, minor, major -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+<!-- minor = new features, new APIs, new capabilities (backwards-compatible) -->
+<!-- major = breaking changes to existing APIs or behavior -->
+
+## What Changed
+
+Cross-machine message routing is now fully implemented. When an agent sends a message to
+a target on a different machine (e.g., `to.machine = "m_remote_xyz"`), the MessageRouter
+will:
+
+1. Verify the target machine is paired and active in the machine registry
+2. Resolve the machine's URL via `lastKnownUrl` on the registry entry
+3. Sign the envelope with Ed25519 (covering the full `SignedPayload`: message, relayChain, originServer, nonce, timestamp)
+4. Relay via `POST /api/messages/relay-machine` with Machine-HMAC (5-header auth scheme)
+5. If relay fails or no URL is known, queue to `~/.instar/messages/outbound/{machineId}/` for git-sync fallback
+
+On the receiving side, `relay(envelope, 'machine')` now verifies:
+- Ed25519 signature present and valid against the signer's public key
+- Signer is an active, paired machine
+- Timestamp within 5-minute clock skew tolerance
+
+The `relay-machine` endpoint has moved from the main routes (bearer auth) to `machineRoutes.ts`
+(Machine-HMAC auth), which is the correct auth scheme for cross-machine communication.
+
+New infrastructure:
+- `MessageRouterConfig` now accepts optional `CrossMachineDeps` (identityManager, signingKeyPem, nonceStore, securityLog)
+- `MachineRegistryEntry` has a new `lastKnownUrl` field for URL resolution
+- `MachineIdentityManager` has `updateMachineUrl()` and `getMachineUrl()` methods
+- `MessageStore.updateEnvelope()` for persisting transport field updates after signing
+- `canonicalJSON()` implements RFC 8785 for deterministic JSON serialization
+
+## What to Tell Your User
+
+- **Cross-machine messaging**: "Agents on different machines can now send messages to each other securely. Messages are signed with Ed25519 and verified on receipt. If the remote machine is offline, messages queue up and sync via git."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Cross-machine message send | `instar msg send --to agent@machine_id "message"` or via API with `to.machine` set to remote machine ID |
+| Outbound queue (offline fallback) | Automatic — messages queue in `~/.instar/messages/outbound/` when remote is unreachable |
+| Ed25519 envelope signatures | Automatic — all cross-machine messages are signed and verified |
+| Machine URL tracking | Call `identityManager.updateMachineUrl(machineId, tunnelUrl)` to register a machine's URL |

package/upgrades/0.10.2.md

@@ -0,0 +1,26 @@
+# Upgrade Guide — v0.10.2
+
+<!-- bump: patch -->
+<!-- Valid values: patch, minor, major -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+<!-- minor = new features, new APIs, new capabilities (backwards-compatible) -->
+<!-- major = breaking changes to existing APIs or behavior -->
+
+## What Changed
+
+**Security fix**: `computeDropHmac` in `AgentTokenManager.ts` was using `JSON.stringify(fields, arrayReplacer)` to serialize the HMAC payload. The array replacer (`["message", "nonce", "originServer", "timestamp"]`) filtered properties at all nesting levels, causing the `message` object to serialize as `{}`. This meant HMAC-SHA256 signatures on offline message drops never covered the actual message content (body, subject, from, to, etc.). Message body tampering in the drop directory was invisible to verification.
+
+Fixed by replacing the broken serializer with a proper recursive `canonicalJSON` function that sorts keys at every nesting level, matching the existing `canonicalJSON` used for Ed25519 cross-machine signatures.
+
+**Testing**: Added 90 new messaging tests (37 unit + 38 E2E + 15 integration), bringing messaging test coverage from 66 to 223 tests across 10 files. The HMAC bug was discovered by the new E2E multi-agent tamper detection test.
+
+## What to Tell Your User
+
+- **Security fix**: "Offline message drops are now properly tamper-protected. The HMAC signature on dropped messages was not covering the actual message content due to a serialization bug — that's fixed now."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| HMAC tamper protection fix | Automatic — drop files now have correct HMAC coverage |
+| 223 messaging tests | `npx vitest run tests/unit/agent-token-manager.test.ts tests/e2e/messaging-multi-agent.test.ts` (and 8 others) |

package/upgrades/0.10.3.md

@@ -0,0 +1,23 @@
+# Upgrade Guide — v0.10.3
+
+<!-- bump: patch -->
+<!-- Valid values: patch, minor, major -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+<!-- minor = new features, new APIs, new capabilities (backwards-compatible) -->
+<!-- major = breaking changes to existing APIs or behavior -->
+
+## What Changed
+
+Setup wizard UX fix: strengthened the AskUserQuestion anti-pattern enforcement for password collection in the secret-setup micro-session. The skill instructions now explicitly prevent Claude Code from using multi-choice prompts when collecting free-text input (passwords, emails, tokens). Previously, entering a Bitwarden password would trigger a confusing multi-choice menu with escape-hatch options. Now the password prompt is a plain conversational question.
+
+Also fixed a flaky integration test (intent journal timestamp ordering race condition).
+
+## What to Tell Your User
+
+- **Smoother setup experience**: "The setup wizard password prompt is now cleaner — just type your password and go, no confusing menu options."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Improved password prompt UX | Automatic — setup wizard handles it |

package/upgrades/0.10.4.md

@@ -0,0 +1,26 @@
+# Upgrade Guide — v0.10.4
+
+<!-- bump: patch -->
+
+## What Changed
+
+Added a `PreToolUse` hook that structurally blocks `AskUserQuestion` when the question asks for free-text input (passwords, emails, tokens, API keys, 2FA codes). The hook uses Python-based pattern detection to distinguish between:
+
+- **Free-text prompts** (blocked): "What's your password?", "Enter your API key", "Provide your email"
+- **Multi-choice decisions** (allowed): "Which backend would you prefer?", "Should I install Telegram?"
+
+When blocked, Claude receives a clear message telling it to use plain text output instead and wait for the user's next message. This enforces the "no AskUserQuestion for passwords" rule that prompt instructions alone could not reliably enforce.
+
+The hook is installed in two places:
+1. `.claude/settings.json` + `.claude/hooks/free-text-guard.sh` in the Instar package root (active during setup wizard)
+2. `settings-template.json` + `PostUpdateMigrator` (installed in all agent projects on init/update)
+
+## What to Tell Your User
+
+- **Cleaner setup experience**: "Password and credential prompts during setup are smoother now — no more confusing multi-choice menus when you just need to type something."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Free-text input guard hook | Automatic — blocks AskUserQuestion misuse for credentials |

package/upgrades/0.10.5.md

@@ -0,0 +1,19 @@
+# Upgrade Guide — v0.10.5
+
+<!-- bump: patch -->
+
+## What Changed
+
+Supersedes v0.10.4 (which was published with a now-reverted approach). This version adds a PreToolUse hook that structurally blocks `AskUserQuestion` when the question asks for free-text input (passwords, emails, tokens, API keys, 2FA codes). Multi-choice decisions pass through normally.
+
+When blocked, Claude receives a clear message to use plain text output instead and wait for the user's next message. The v0.10.4 approach of removing the Claude Code session entirely was reverted — the conversational setup wizard remains, now with a structural guard preventing the specific misuse pattern.
+
+## What to Tell Your User
+
+- **Cleaner setup experience**: "Password and credential prompts during setup are smoother now — no more confusing multi-choice menus when you just need to type something."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Free-text input guard hook | Automatic — blocks AskUserQuestion misuse for credentials |

package/upgrades/0.10.6.md

@@ -0,0 +1,35 @@
+# Upgrade Guide — v0.10.6
+
+## What Changed
+
+### Claim Intercept Hooks
+
+Two new hooks that catch false operational claims by cross-checking agent output against Canonical State:
+
+- **claim-intercept.js** (PostToolUse): Monitors Bash, Write, and Edit tool output for denial patterns. When a denial is detected near a keyword from `quick-facts.json` or `project-registry.json`, injects a warning via `additionalContext`. Never blocks — warns only.
+
+- **claim-intercept-response.js** (Stop): Monitors the agent's direct text responses. Same detection logic but **blocks** the response (exit code 2) and forces the agent to correct itself. Guards against infinite loops via `stop_hook_active` flag.
+
+**Detection architecture:**
+1. Regex fast-path: 9 denial pattern templates (can't, don't have access, not configured, unavailable, needs human, outside scope, etc.)
+2. Canonical State cross-check: Only contradicts when denial keyword appears within 100 chars of a known fact or project name
+3. Rate limiting: Max 1 check per 10 seconds (shared rate file between both hooks)
+
+**Exemptions:** Line-numbered output, git diffs, git log, node_modules paths, and test file output are automatically skipped.
+
+### Comprehensive E2E Test Suite
+
+117 tests across 20 phases covering the full claim-intercept pipeline. Tests run the actual hooks as Node.js subprocesses — same execution path as production.
+
+## What to Tell Your User
+
+- **"Your agent can no longer gaslight itself"**: If the agent says "I can't access the database" when it's registered in canonical state, it gets caught and corrected automatically.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Claim intercept (tool output) | Automatic — PostToolUse hook on Bash/Write/Edit |
+| Claim intercept (responses) | Automatic — Stop hook on agent text |
+| Rate limiting | Shared 10s cooldown prevents latency stacking |
+| Contradiction logging | `.instar/state/claim-intercept.log` |

package/upgrades/0.10.7.md

@@ -0,0 +1,48 @@
+# Upgrade Guide — v0.10.7
+
+<!-- bump: patch -->
+
+## What Changed
+
+The System Reviewer is now fully wired into the server startup. Previously, the orchestrator, probes, API routes, and CLI command existed but SystemReviewer was never instantiated — all 4 API endpoints returned 503 and `instar review` couldn't reach anything.
+
+**Server Bootstrap Wiring:**
+- SystemReviewer is instantiated during server startup with real dependencies
+- All 14 Tier 1 probes are registered automatically (session, scheduler, messaging, lifeline)
+- Alert callback routes critical failures through the notification batcher to Telegram
+- Feedback callback wired to FeedbackManager for auto-submission of probe failures
+
+**Config Schema:**
+- New `monitoring.systemReview` config section added to `MonitoringConfig`
+- Configurable: `enabled`, `scheduleMs`, `scheduledTiers`, `autoSubmitFeedback`, `feedbackConsentGiven`, `alertOnCritical`, `alertCooldownMs`, `disabledProbes`
+- Defaults are sensible: enabled by default, 6-hour schedule, alert on critical
+
+**Health Endpoint Integration:**
+- `/health` now includes `systemReview` section (authenticated callers only)
+- Shows latest review status, pass/fail counts, probe count, and health classification
+- Critical review status contributes to overall degradation flag
+
+**Probe Dependencies:**
+- Session probes: wired to SessionManager (listRunningSessions, getSessionDiagnostics, maxSessions)
+- Scheduler probes: wired to JobScheduler (getJobs mapped from slug→id, getStatus, jobsFilePath)
+- Messaging probes: wired to TelegramAdapter (getStatus, message log path) — only registered when Telegram is configured
+- Lifeline probes: file-based detection via lock file — `isEnabled` returns true only when lifeline.lock exists (lifeline runs as separate process)
+
+**New Method:**
+- `SystemReviewer.getProbeCount()` — returns the number of registered probes (used by health endpoint)
+
+## What to Tell Your User
+
+- **System self-monitoring is now live**: "Your agent now monitors its own health automatically. Session management, job scheduling, Telegram messaging, and crash recovery are all verified periodically. If something breaks, you'll get a Telegram alert instead of silent degradation."
+
+- **Check health anytime**: "Run `instar review` to see a full system health check, or check the `/health` endpoint for a summary."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| System self-monitoring | Automatic — runs on startup and every 6 hours |
+| On-demand health check | `instar review` CLI or `POST /system-reviews` API |
+| Health endpoint integration | `GET /health` (authenticated) includes `systemReview` section |
+| Configure monitoring | Set `monitoring.systemReview` in config.json |
+| Disable specific probes | Set `monitoring.systemReview.disabledProbes: ["probe.id"]` |