instar 1.2.61 → 1.2.63

package/README.md

@@ -200,6 +200,16 @@ The AI systems we build today set precedents for how AI is treated tomorrow. **T
 
 > **Deep dive:** [Philosophy](https://instar.sh/concepts/philosophy/)
 
+## The Living Constitution
+
+Instar's engineering principles aren't a static style guide — they're a **living constitution**. The [Standards Registry](https://instar.sh/foundations/standards-registry/) codifies each one as a rule, what it means in practice, the *failure it was earned from*, and its trace back to the one founding goal: a coherent, self-evolving agent. Nineteen articles across five families (Root, Substrate, Building, Shipping, Interaction), plus the Genesis story and the AWG positioning on the ethics of instantiating agents.
+
+It's not decoration — it's a working part of the machine. The spec-review conformance gate checks every draft against it, and the registry grows the same way the framework was built: the agent proposes a new standard with its story, the operator ratifies it.
+
+The registry is the first tangible artifact of a larger vision: the [North Star — Continuous Working Awareness](https://instar.sh/foundations/north-star/). The aim is an agent that never silently loses track of something that mattered — capturing relevant context automatically, keeping it warm while it matters, re-surfacing it the moment it's needed, and letting it fade when it stops — across three facets that are really one: awareness of the world, of itself, and of its own standards.
+
+> **Read the constitution:** [Standards Registry](https://instar.sh/foundations/standards-registry/) · [North Star](https://instar.sh/foundations/north-star/)
+
 ## iMessage Setup (macOS)
 
 iMessage support lets your agent send and receive iMessages on macOS. Messages are read directly from the native Messages database and sent via the [`imsg`](https://github.com/steipete/imsg) CLI.

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,CA60LtE;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,
@@ -5362,6 +5398,61 @@ export async function startServer(options) {
                         beforeHadCallback(entry);
                     observeInboundMessage(humanAsDetectorLog, entry);
                 };
+                // ── Topic-Intent capture loop (rung 0 of continuous-working-awareness) ─
+                // The "clerk" that fills the topic-intent store from live conversation so
+                // the per-topic briefing + ArcCheck have real material (closes the
+                // shipped-but-asleep gap — the store/routes/briefing all existed but
+                // nothing ever invoked ingest()). Chains the prior callback; capture is
+                // fire-and-forget + degrade-safe so it NEVER blocks or slows delivery.
+                // Spec: docs/specs/topic-intent-capture-loop.md.
+                if (sharedIntelligence && (config.topicIntent?.capture?.enabled ?? true)) {
+                    try {
+                        const { TopicIntentExtractor, createLlmExtractFn } = await import('../core/TopicIntentExtractor.js');
+                        const { createCaptureLoop, createQueuedIntelligence } = await import('../core/TopicIntentCapture.js');
+                        // Transport: route every extraction through sharedLlmQueue (background
+                        // lane → yields to interactive work, respects the daily cap), with the
+                        // call itself delegating to sharedIntelligence (subscription/REPL-pool,
+                        // never raw API — acceptance #6).
+                        const queuedIntelligence = createQueuedIntelligence(sharedIntelligence, (lane, fn, costCents) => sharedLlmQueue.enqueue(lane, fn, costCents));
+                        const captureExtractFn = createLlmExtractFn(queuedIntelligence, (reason, topicId) => {
+                            topicIntentStore.bumpCaptureCounters(topicId, reason === 'no-intelligence'
+                                ? { degraded_no_intelligence: 1 }
+                                : { degraded_cap_or_error: 1 });
+                        });
+                        const captureExtractor = new TopicIntentExtractor(topicIntentStore, captureExtractFn);
+                        const captureLoop = createCaptureLoop({
+                            extractor: captureExtractor,
+                            store: topicIntentStore,
+                            topicMemory,
+                            // Skip capture under sustained quota pressure (load-shedding).
+                            shouldShed: () => {
+                                const r = quotaTracker?.getRecommendation();
+                                return r === 'critical' || r === 'stop';
+                            },
+                            // Per-topic runaway guard beyond the pre-filter.
+                            rateCeiling: { maxPerWindow: 30, windowMs: 60_000 },
+                        });
+                        const beforeCaptureCb = telegram.onMessageLogged;
+                        telegram.onMessageLogged = (entry) => {
+                            if (beforeCaptureCb)
+                                beforeCaptureCb(entry);
+                            // Fire-and-forget — capture latency must never reach the delivery path.
+                            void captureLoop({
+                                messageId: entry.messageId,
+                                topicId: entry.topicId ?? undefined,
+                                text: entry.text,
+                                fromUser: entry.fromUser,
+                                timestamp: entry.timestamp,
+                            });
+                        };
+                        // Anti-"shipped-but-asleep" marker for the wiring-integrity test.
+                        globalThis.__instarTopicIntentCaptureWired = true;
+                        console.log(pc.green('  Topic-intent capture loop wired (per-turn extraction → store)'));
+                    }
+                    catch (err) {
+                        console.warn('[TopicIntentCapture] init failed:', err.message);
+                    }
+                }
                 presenceProxy.start();
                 // ── PromiseBeacon ────────────────────────────────────────────────
                 // Watches beacon-enabled commitments and emits ⏳ heartbeats so the