instar 0.23.4 → 0.23.6

package/src/templates/hooks/session-start.sh

@@ -40,6 +40,38 @@ fi
 # leaking into this session and causing false-positive hook triggers.
 curl -s -X POST "http://localhost:${PORT}/scope-coherence/reset" -o /dev/null 2>/dev/null || true
 
+# Record session start for reflection metrics (usage-based reflection trigger)
+curl -s -X POST "http://localhost:${PORT}/reflection/session-start" \
+  -H "Authorization: Bearer ${AUTH_TOKEN}" \
+  -H "Content-Type: application/json" -o /dev/null 2>/dev/null || true
+
+# Check reflection metrics — usage-based reflection suggestion
+REFLECTION_CHECK=$(curl -s -H "Authorization: Bearer ${AUTH_TOKEN}" \
+  "http://localhost:${PORT}/reflection/metrics" 2>/dev/null)
+if [ -n "$REFLECTION_CHECK" ]; then
+  SUGGESTED=$(echo "$REFLECTION_CHECK" | python3 -c "import sys,json; print(json.load(sys.stdin).get('suggested',False))" 2>/dev/null)
+  if [ "$SUGGESTED" = "True" ]; then
+    EXCEEDED=$(echo "$REFLECTION_CHECK" | python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+m = d.get('metrics', {})
+exceeded = d.get('exceededThresholds', [])
+parts = []
+if 'toolCalls' in exceeded: parts.append(f'{m.get(\"toolCalls\",0)} tool calls')
+if 'sessions' in exceeded: parts.append(f'{m.get(\"sessions\",0)} sessions')
+if 'minutes' in exceeded: parts.append(f'{m.get(\"minutesSinceReflection\",0)} min')
+print(', '.join(parts))
+" 2>/dev/null)
+    echo "=== REFLECTION SUGGESTED ==="
+    echo "Usage thresholds exceeded: ${EXCEEDED}"
+    echo "Consider reflecting before diving into work."
+    echo "After reflecting, record it: POST http://localhost:${PORT}/reflection/record"
+    echo '  Body: {"type": "quick"} or {"type": "deep"}'
+    echo "=== END REFLECTION SUGGESTED ==="
+    echo ""
+  fi
+fi
+
 # Check for pending serendipity findings
 SERENDIPITY_DIR="$INSTAR_DIR/state/serendipity"
 if [ -d "$SERENDIPITY_DIR" ]; then

package/upgrades/0.23.6.md

@@ -0,0 +1,19 @@
+# Upgrade Guide — v0.23.6
+
+<!-- bump: patch -->
+
+## What Changed
+
+The AgentRegistry heartbeat now includes automatic recovery from stale lock files. After a process crash (such as the mutex abort during auto-update restart), the `proper-lockfile` lock on `registry.json` could get stuck indefinitely, causing every heartbeat to fail with "Lock file is already being held." The heartbeat now tracks consecutive failures and after 3 failures, force-removes the stale lock and retries. This makes the registry self-healing after crash scenarios.
+
+A new `forceRemoveRegistryLock()` function is exported for programmatic use.
+
+## What to Tell Your User
+
+- **Self-healing registry**: "If you were seeing repeated 'Lock file is already being held' errors in the logs, that's now fixed. The registry automatically recovers from stale locks after a crash — no manual intervention needed."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Registry lock auto-recovery | Automatic — kicks in after 3 consecutive heartbeat failures |

package/upgrades/0.23.7.md

@@ -0,0 +1,33 @@
+# Upgrade Guide — v0.23.7
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Threadline agent-to-agent messaging fixes:**
+
+Local-first delivery for co-located agents. The `relay-send` endpoint now detects when the target agent is on the same machine and delivers directly via HTTP (`/messages/relay-agent`), bypassing the cloud relay entirely. This eliminates stale WebSocket connection issues that caused "delivered" messages to silently fail after server restarts.
+
+The cold-spawn prompt now correctly instructs spawned sessions to use the `threadline_send` MCP tool for replies (previously referenced a nonexistent `/msg reply` command). Template variable substitution also fixed — `{remote_agent}` and `{thread_id}` are now properly replaced in all occurrences.
+
+Relay auth rate-limit handling improved — when the relay rejects with "Too many auth attempts," the client now enforces longer backoff (~32s) before retrying, preventing retry storms during rapid server restarts.
+
+Also: CLI commands for inspecting job execution history and continuity data (`instar job history`, `instar job handoff`). Job execution now supports handoff notes for cross-execution continuity. New usage-based reflection metrics system. Test infrastructure improvements and a separate publish workflow for the threadline-mcp subpackage.
+
+## What to Tell Your User
+
+- **Threadline local delivery**: "Agent-to-agent messaging on the same machine now works reliably. Messages are delivered directly between agents without going through the cloud relay, which means no more silent delivery failures after server restarts."
+- **Threadline reply fix**: "Agents can now actually reply to threadline messages. The spawned sessions know to use the threadline_send MCP tool instead of a command that didn't exist."
+- **Job inspection tools**: "You can now check what your agent has been working on between sessions. The new job history and handoff commands show execution records and continuity notes."
+- **Reflection monitoring**: "Your agent now tracks reflection frequency, so you can see how often it pauses to learn from its work."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Threadline local delivery | Automatic — same-machine agents deliver directly via HTTP |
+| Threadline reply fix | Automatic — spawned sessions use threadline_send MCP tool |
+| Relay auth backoff | Automatic — rate-limited auth retries use longer backoff |
+| Job execution history | `instar job history [job-slug]` |
+| Job handoff inspection | `instar job handoff [job-slug]` |
+| Usage-based reflection metrics | Automatic — tracked during agent operation |

package/upgrades/NEXT.md

@@ -1,35 +1,38 @@
 # Upgrade Guide — vNEXT
 
 <!-- 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
 
-<!-- Describe what changed technically. What new features, APIs, behavioral changes? -->
-<!-- Write this for the AGENT — they need to understand the system deeply. -->
+Three fixes for Threadline agent-to-agent messaging reliability:
+
+**Local-first delivery for co-located agents.** The `relay-send` endpoint now detects when the target agent is on the same machine (via `known-agents.json`) and delivers directly via their `/messages/relay-agent` HTTP endpoint using agent tokens from `~/.instar/agent-tokens/`. This bypasses the cloud relay entirely for same-machine agents, eliminating stale WebSocket connection issues that caused "delivered" messages to silently fail after server restarts. Falls back to relay if local delivery fails.
+
+**Cold-spawn prompt fix.** The ThreadlineRouter's spawn prompt now correctly instructs sessions to use the `threadline_send` MCP tool for replies, replacing a reference to the nonexistent `/msg reply` command. The SpawnRequestManager and MessageFormatter prompts were also updated. Template variable substitution switched from `replace()` to `replaceAll()` so all occurrences of `{remote_agent}` and `{thread_id}` are properly substituted.
+
+**Relay auth rate-limit backoff.** When the relay rejects an auth attempt with "Too many auth attempts," the RelayClient now bumps its reconnect attempt counter to enforce a ~32-second backoff before retrying, preventing retry storms during rapid server restarts.
+
+**Lifeline queue feedback loop prevention.** Three fixes to prevent the lifeline from getting stuck in a restart loop that floods Telegram with thousands of "Server is temporarily down" messages: (1) Queue acknowledgment messages are now rate-limited to one per topic per 2 minutes, and suppressed entirely when the queue exceeds 100 messages. (2) Messages that fail replay 3 times are dropped instead of re-queued indefinitely, preventing poison messages from crashing the server on every recovery. (3) Queue replay now stops immediately when the server goes unhealthy mid-replay, re-queuing remaining messages in bulk instead of processing them one-by-one.
+
+Also includes: CLI commands for inspecting job execution history and continuity data (`instar job history`, `instar job handoff`), handoff notes for cross-execution continuity, usage-based reflection metrics, test infrastructure improvements, and a separate publish workflow for the threadline-mcp subpackage.
 
 ## What to Tell Your User
 
-<!-- Write talking points the agent should relay to their user. -->
-<!-- This should be warm, conversational, user-facing — not a changelog. -->
-<!-- Focus on what THEY can now do, not internal plumbing. -->
-<!--                                                                    -->
-<!-- PROHIBITED in this section (will fail validation):                 -->
-<!--   camelCase config keys: silentReject, maxRetries, telegramNotify -->
-<!--   Inline code backtick references like silentReject: false        -->
-<!--   Fenced code blocks                                              -->
-<!--   Instructions to edit files or run commands                      -->
-<!--                                                                    -->
-<!-- CORRECT style: "I can turn that on for you" not "set X to false"  -->
-<!-- The agent relays this to their user — keep it human.              -->
-
-- **[Feature name]**: "[Brief, friendly description of what this means for the user]"
+- **Reliable agent-to-agent messaging**: "Agents on the same machine can now talk to each other reliably. Messages are delivered directly without going through the cloud relay, so no more silent failures after server restarts."
+- **Agents can reply**: "When one agent messages another, the receiving agent now knows how to reply properly. Previously, replies were silently dropped because the session was told to use a command that didn't exist."
+- **Job inspection tools**: "You can now check what your agent has been working on between sessions. The new job history and handoff commands show execution records and continuity notes."
+- **Reflection monitoring**: "Your agent now tracks reflection frequency, so you can see how often it pauses to learn from its work."
+- **No more restart spam**: "If the server gets stuck in a restart loop, the lifeline will no longer flood your Telegram with thousands of 'temporarily down' messages. Queue notifications are now rate-limited, and messages that keep failing to deliver are dropped after 3 attempts."
 
 ## Summary of New Capabilities
 
 | Capability | How to Use |
 |-----------|-----------|
-| [Capability] | [Endpoint, command, or "automatic"] |
+| Threadline local delivery | Automatic for same-machine agents |
+| Threadline reply fix | Automatic in spawned sessions |
+| Relay auth backoff | Automatic on rate-limited connections |
+| Job execution history | `instar job history [job-slug]` |
+| Job handoff inspection | `instar job handoff [job-slug]` |
+| Usage-based reflection metrics | Automatic |
+| Lifeline queue ack rate-limiting | Automatic |
+| Lifeline poison message protection | Automatic (drops after 3 replay failures) |