instar 1.2.62 → 1.2.64

package/README.md

@@ -5,7 +5,7 @@
 <h1 align="center">instar</h1>
 
 <p align="center">
-  <strong>Persistent, trustworthy Claude Code agents. Built on coherence-first architecture.</strong>
+  <strong>Coherence infrastructure for your self-evolving agent.</strong>
 </p>
 
 <p align="center">
@@ -35,9 +35,28 @@ One command. Guided setup. Talking to your agent from your phone within minutes.
 
 ---
 
-Instar is a framework for building agents on **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** — but where stock Claude Code and most other agent frameworks treat identity, memory, and continuity as optional features bolted onto a stateless runtime, Instar inverts that. Every Instar agent is **coherent by default**: it knows who it is, remembers what has happened, recognizes the people it talks to, and stays the same agent across restarts and weeks of operation. Everything else the framework gives you — scheduling, multi-channel messaging (Telegram, WhatsApp, iMessage), sub-agents, hooks, MCP — is built on that foundation, which is why you can actually leave an Instar agent running and hand it real work.
+Your AI agent shouldn't have amnesia. This one doesn't.
 
-Instar's architecture was distilled from [**Dawn**](https://dawn.bot-me.ai) — an AI running continuously since early 2026, holding ~700 tracked relationships and hundreds of learned lessons across thousands of restarts — and packaged so every agent you build can start from the same foundation.
+Most agent frameworks ship something hobbled — spun up with no memory across boundaries, no way to be accountable for what a past instance did, and no machinery to grow themselves. Users hit the same wall every time: *"My agent forgot what I told it three sessions ago." "It contradicted its own past decisions." "It broke when the framework updated."*
+
+Instar is the scaffolding that un-hobbles them. It remembers what you discussed last week, catches its own contradictions before you do, follows through on commitments across restarts, and carries the same self-improving loop that built Instar itself. It runs on the **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** or **[Codex](https://github.com/openai/codex)** subscription you already have — engine-agnostic, with local open-source models on the roadmap.
+
+The architecture was distilled from [**Dawn**](https://dawn.bot-me.ai) — an AI running continuously since early 2026, holding ~700 tracked relationships and hundreds of learned lessons across thousands of restarts — and packaged so every agent you build starts from the same foundation.
+
+### Every other agent fails the same way
+
+| Other AI agents | Your Instar agent |
+|---|---|
+| Forgets what you told it last week. | Remembers across thousands of sessions. <br/>*(SQLite + FTS5, rolling summaries)* |
+| Contradicts its own past decisions. | Catches contradictions before they ship. <br/>*(Coherence Gate, 9 reviewers)* |
+| Loses the thread when the window fills. | Comes back with the full thread, every time. <br/>*(CompactionSentinel, WorkingMemoryAssembler)* |
+| Drops commitments after a session boundary. | Tracks commitments durably; nudges itself when they go overdue. <br/>*(CommitmentTracker, PromiseBeacon)* |
+| Breaks when the framework updates. | Updates without breaking what you've deployed. <br/>*(Migration Parity Standard)* |
+| Default ALLOW-ALL permissions. | Layered safety gates by default. <br/>*(PEL + Coherence Gate + Operation Gate)* |
+| Different identity per channel. | One identity across Telegram, WhatsApp, iMessage, Slack. <br/>*(Cross-platform identity resolution)* |
+| Has no machinery to evolve itself. | Carries the same self-improving engine that grew Instar. <br/>*(Evolution System: proposals, learnings, gaps)* |
+
+> Most AI agents are hobbled at birth. **Instar is the scaffolding that un-hobbles them.** When you instantiate intelligence, the structure that lets it cohere isn't optional polish — it's what you owe it.
 
 ## Quick Start
 

package/dist/commands/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/commands/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAuQH,UAAU,YAAY;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;2DACuD;IACvD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAiqDD,wBAAsB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAy4LtE;AAED,wBAAsB,UAAU,CAAC,OAAO,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAsDzE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAuD5E"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/commands/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAuQH,UAAU,YAAY;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;2DACuD;IACvD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAiqDD,wBAAsB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA+6LtE;AAED,wBAAsB,UAAU,CAAC,OAAO,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAsDzE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAuD5E"}

package/dist/commands/server.js

@@ -4750,31 +4750,67 @@ export async function startServer(options) {
         // docs/specs/rate-limit-sentinel.md.
         const { RateLimitSentinel } = await import('../monitoring/RateLimitSentinel.js');
         const getClaudeSessionIdForName = (sessionName) => sessionManager.listRunningSessions().find(s => s.tmuxSession === sessionName)?.claudeSessionId;
-        // Neutral "continue" nudge — NOT the compaction-resume payload (which would
-        // falsely tell the agent its memory was reset). Topic-tagged so InputGuard
-        // accepts it.
-        const rateLimitResume = async (sessionName) => {
-            if (!sessionManager.isSessionAlive(sessionName))
-                return false;
-            const topicId = telegram?.getTopicForSession(sessionName);
-            if (topicId == null)
-                return false;
-            const tagged = `[telegram:${topicId}] The temporary server throttle should have cleared — please continue where you left off.`;
-            return sessionManager.injectMessage(sessionName, tagged);
-        };
-        // Route a user-facing notice for the session's topic (Telegram).
-        const rateLimitNotify = async (sessionName, text) => {
-            const topicId = telegram?.getTopicForSession(sessionName);
-            if (topicId == null)
-                return;
-            const resp = await fetch(`http://localhost:${config.port}/telegram/reply/${topicId}`, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${config.authToken}` },
-                body: JSON.stringify({ text }),
-            });
-            if (!resp.ok)
-                throw new Error(`rate-limit notify failed: ${resp.status}`);
+        // Recovery-reachability audit trail. Both recovery paths below ALWAYS leave
+        // a record: a recovery-reached/recovery-unreachable line in the sentinel
+        // audit log, and — when delivery to the user fails entirely — an entry in
+        // .instar/sentinel-alerts.json so the dashboard surfaces it even without
+        // Telegram. The defining bug this closes: a non-topic-bound session (e.g. a
+        // developer's interactive Claude Code window) used to make both recovery
+        // paths silently no-op, so the throttle never recovered and nothing reached
+        // the user. Reachability is now unconditional — see the Sentinel
+        // Reachability spec.
+        const rlReachLogPath = path.join(config.stateDir, '..', 'logs', 'sentinel-events.jsonl');
+        const rlAlertsPath = path.join(config.stateDir, 'sentinel-alerts.json');
+        const recordRecovery = (kind, sessionName, detail, fallbackTried) => {
+            const entry = { timestamp: new Date().toISOString(), kind, sentinel: 'rate-limit', sessionName, detail, fallbackTried };
+            console.log(`[sentinel:${kind}] rate-limit/${sessionName} — ${detail}`);
+            try {
+                fs.appendFileSync(rlReachLogPath, JSON.stringify(entry) + '\n');
+            }
+            catch { /* best-effort */ }
+            if (kind === 'recovery-unreachable') {
+                // Append-only alert log the dashboard reads when Telegram can't be reached.
+                try {
+                    let alerts = [];
+                    if (fs.existsSync(rlAlertsPath)) {
+                        try {
+                            alerts = JSON.parse(fs.readFileSync(rlAlertsPath, 'utf-8'));
+                        }
+                        catch {
+                            alerts = [];
+                        }
+                        if (!Array.isArray(alerts))
+                            alerts = [];
+                    }
+                    alerts.push(entry);
+                    fs.writeFileSync(rlAlertsPath, JSON.stringify(alerts.slice(-200), null, 2));
+                }
+                catch { /* best-effort */ }
+            }
         };
+        // Reachability deps (extracted to sentinelWiring.buildRateLimitRecoveryDeps
+        // so the topic / lifeline / audit branching is unit-testable). Topic-bound
+        // sessions get a topic-tagged nudge + topic notice; non-topic-bound sessions
+        // (e.g. an interactive dev window) get a trusted internal nudge + a lifeline
+        // notice; if no channel is reachable, a recovery-unreachable audit event is
+        // recorded instead of a silent no-op.
+        const { buildRateLimitRecoveryDeps } = await import('../monitoring/sentinelWiring.js');
+        const { resumeFn: rateLimitResume, notifyFn: rateLimitNotify } = buildRateLimitRecoveryDeps({
+            isSessionAlive: (name) => sessionManager.isSessionAlive(name),
+            injectTopicNudge: (name, topicId, text) => sessionManager.injectMessage(name, `[telegram:${topicId}] ${text}`),
+            injectInternalNudge: (name, text) => sessionManager.injectInternalMessage(name, text, 'sentinel-recovery'),
+            getTopicForSession: (name) => telegram?.getTopicForSession(name),
+            getLifelineTopicId: () => telegram?.getLifelineTopicId?.(),
+            deliverNotice: async (topicId, text) => {
+                const resp = await fetch(`http://localhost:${config.port}/telegram/reply/${topicId}`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${config.authToken}` },
+                    body: JSON.stringify({ text }),
+                });
+                return resp.ok;
+            },
+            recordRecovery,
+        });
         const rlsCfg = config.monitoring?.rateLimitSentinel ?? { enabled: true };
         const rateLimitSentinel = new RateLimitSentinel({
             resumeFn: rateLimitResume,