instar 1.3.443 → 1.3.445

package/README.md

@@ -18,7 +18,7 @@
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/instar">npm</a> · <a href="https://github.com/JKHeadley/instar">GitHub</a> · <a href="https://instar.sh">instar.sh</a> · <a href="https://instar.sh/introduction/">Docs</a>
+  <a href="https://www.npmjs.com/package/instar">npm</a> · <a href="https://github.com/JKHeadley/instar">GitHub</a> · <a href="https://instar.sh">instar.sh</a> · <a href="https://instar.sh/introduction/">Docs</a> · <a href="https://instar.sh/exo3">EXO&nbsp;3.0</a>
 </p>
 
 ---
@@ -116,6 +116,14 @@ An agent that forgets what you discussed yesterday, doesn't recognize someone it
 
 > **Deep dive:** [The Coherence Problem](https://instar.sh/concepts/coherence/) · [Values & Identity](https://instar.sh/concepts/values/) · [Coherence Is Safety](https://instar.sh/concepts/safety/)
 
+## EXO 3.0 — governed by your organization's intent
+
+Instar independently converged on Salim Ismail's **EXO 3.0 / "The Organizational Singularity"** framework: the idea that an organization's purpose should be encoded as *machine-readable* intent — "in code, not culture" — that actually **governs** its agents rather than just inspiring them. Instar was built around coherence before the framework existed, and the overlap turned out to be close to the line.
+
+We didn't just claim it works. We ran controlled experiments — same model, same requests, with the organization's intent switched off as the control — to show the intent itself is what changes the agent's behavior. The engine stays **neutral**: it enforces whatever intent a deploying organization gives it, never Instar's own values. Two case studies enforce two very different fictional companies' values equally well, neither of them ours.
+
+> **See the controlled proof → [instar.sh/exo3](https://instar.sh/exo3)** — two governed-vs-ungoverned case studies, with full transcripts.
+
 ## Features
 
 | Feature | Description | Docs |

package/dist/commands/server.d.ts

@@ -12,6 +12,25 @@ import { TelegramAdapter } from '../messaging/TelegramAdapter.js';
 import { TopicMemory } from '../memory/TopicMemory.js';
 import { QuotaTracker } from '../monitoring/QuotaTracker.js';
 import { UserManager } from '../users/UserManager.js';
+/**
+ * Pure: should the emergency "fix command" gate intercept this message?
+ *
+ * Fix commands ("fix auth", "restart sessions", "clean processes", …) are
+ * mechanical server-side operations that only make sense in the Agent Attention
+ * topic, where the agent posts actionable notifications the user taps to resolve.
+ * In ANY other topic, a message that merely starts with "restart" / "fix " /
+ * "clean " is ordinary conversation ("restart the build", "fix the login page",
+ * "clean up this function") and must route to the session — never be swallowed.
+ *
+ * The previous logic ran this verb test in every topic and, on a non-attention
+ * topic, bounced the message back with "I didn't recognize that command" while
+ * also swallowing it (the gate `return`s). That is exactly why a user trying to
+ * revive a stuck session by typing "restart sessions" in that session's own
+ * topic never reached the session: the gate ate the message and replied with a
+ * help list that even advertised "restart sessions" as valid. Scoping the gate
+ * to the attention topic closes that hole.
+ */
+export declare function shouldInterceptFixCommand(text: string, topicId: number, attentionTopicId: number | null | undefined): boolean;
 interface StartOptions {
     foreground?: boolean;
     dir?: string;
@@ -19,7 +38,7 @@ interface StartOptions {
      *  Commander maps --no-telegram to telegram: false. */
     telegram?: boolean;
 }
-export declare function wireTelegramRouting(telegram: TelegramAdapter, sessionManager: SessionManager, quotaTracker?: QuotaTracker, topicMemory?: TopicMemory, userManager?: UserManager, fixCommandHandler?: (topicId: number, text: string) => Promise<boolean>, getHubDeps?: () => import('../threadline/hubCommands.js').HubBindDeps | null, getTopicOperatorStore?: () => import('../users/TopicOperatorStore.js').TopicOperatorStore | null): void;
+export declare function wireTelegramRouting(telegram: TelegramAdapter, sessionManager: SessionManager, quotaTracker?: QuotaTracker, topicMemory?: TopicMemory, userManager?: UserManager, fixCommandHandler?: (topicId: number, text: string) => Promise<boolean>, getHubDeps?: () => import('../threadline/hubCommands.js').HubBindDeps | null, getTopicOperatorStore?: () => import('../users/TopicOperatorStore.js').TopicOperatorStore | null, getAttentionTopicId?: () => number | null | undefined): void;
 export declare function startServer(options: StartOptions): Promise<void>;
 export declare function stopServer(options: {
     dir?: string;

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;AAaH,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAS3D,OAAO,EAAE,eAAe,EAAiC,MAAM,iCAAiC,CAAC;AAuBjG,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAGvD,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAiG7D,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AA6JtD,UAAU,YAAY;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;2DACuD;IACvD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AA05BD,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,eAAe,EACzB,cAAc,EAAE,cAAc,EAC9B,YAAY,CAAC,EAAE,YAAY,EAC3B,WAAW,CAAC,EAAE,WAAW,EACzB,WAAW,CAAC,EAAE,WAAW,EACzB,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,EAGvE,UAAU,CAAC,EAAE,MAAM,OAAO,8BAA8B,EAAE,WAAW,GAAG,IAAI,EAK5E,qBAAqB,CAAC,EAAE,MAAM,OAAO,gCAAgC,EAAE,kBAAkB,GAAG,IAAI,GAC/F,IAAI,CAyUN;AA2lBD,wBAAsB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAgtUtE;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;AAaH,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAS3D,OAAO,EAAE,eAAe,EAAiC,MAAM,iCAAiC,CAAC;AAuBjG,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAGvD,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAiG7D,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAsBtD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,gBAAgB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC1C,OAAO,CAUT;AAyID,UAAU,YAAY;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;2DACuD;IACvD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AA05BD,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,eAAe,EACzB,cAAc,EAAE,cAAc,EAC9B,YAAY,CAAC,EAAE,YAAY,EAC3B,WAAW,CAAC,EAAE,WAAW,EACzB,WAAW,CAAC,EAAE,WAAW,EACzB,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,EAGvE,UAAU,CAAC,EAAE,MAAM,OAAO,8BAA8B,EAAE,WAAW,GAAG,IAAI,EAK5E,qBAAqB,CAAC,EAAE,MAAM,OAAO,gCAAgC,EAAE,kBAAkB,GAAG,IAAI,EAKhG,mBAAmB,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,GACpD,IAAI,CA0UN;AA2lBD,wBAAsB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAyvUtE;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

@@ -144,6 +144,34 @@ import { toInjection } from '../types/pipeline.js';
 import { UserManager } from '../users/UserManager.js';
 import { formatUserContextForSession, hasUserContext } from '../users/UserContextBuilder.js';
 import { SafeFsExecutor } from '../core/SafeFsExecutor.js';
+/**
+ * Pure: should the emergency "fix command" gate intercept this message?
+ *
+ * Fix commands ("fix auth", "restart sessions", "clean processes", …) are
+ * mechanical server-side operations that only make sense in the Agent Attention
+ * topic, where the agent posts actionable notifications the user taps to resolve.
+ * In ANY other topic, a message that merely starts with "restart" / "fix " /
+ * "clean " is ordinary conversation ("restart the build", "fix the login page",
+ * "clean up this function") and must route to the session — never be swallowed.
+ *
+ * The previous logic ran this verb test in every topic and, on a non-attention
+ * topic, bounced the message back with "I didn't recognize that command" while
+ * also swallowing it (the gate `return`s). That is exactly why a user trying to
+ * revive a stuck session by typing "restart sessions" in that session's own
+ * topic never reached the session: the gate ate the message and replied with a
+ * help list that even advertised "restart sessions" as valid. Scoping the gate
+ * to the attention topic closes that hole.
+ */
+export function shouldInterceptFixCommand(text, topicId, attentionTopicId) {
+    if (!attentionTopicId || topicId !== attentionTopicId)
+        return false;
+    const cmd = text.trim().toLowerCase();
+    return (cmd.startsWith('fix ') ||
+        cmd.startsWith('clean ') ||
+        cmd.startsWith('restart') ||
+        cmd === 'fix' ||
+        cmd === 'clean');
+}
 /**
  * Handle "fix X" and "clean X" commands from Agent Attention notifications.
  * These are mechanical server-side operations — no Claude session needed.
@@ -1100,7 +1128,12 @@ getHubDeps,
 // the SAME instance the routes use (a second instance on the same file would
 // lose updates between the two in-memory caches). Know Your Principal #898,
 // increment 2e: the polling-path operator auto-bind.
-getTopicOperatorStore) {
+getTopicOperatorStore, 
+// Late-bound resolver for the Agent Attention topic id. The emergency
+// fix-command gate (below) only fires in that topic; everywhere else a
+// message starting with restart/fix/clean is normal conversation and must
+// route to the session instead of being swallowed.
+getAttentionTopicId) {
     // Guard: tracks which topic IDs have a spawn in progress.
     // Prevents duplicate concurrent spawns for the same topic when messages
     // arrive faster than the async spawn completes.
@@ -1214,34 +1247,35 @@ getTopicOperatorStore) {
         // ── Fix commands from notification messages ──────────────────────
         // Handle "fix auth", "clean processes", "restart", etc. directly
         // in the server process — no need to spawn a Claude session for these.
-        if (fixCommandHandler) {
-            const cmdText = text.trim().toLowerCase();
-            const isFixCommand = cmdText.startsWith('fix ') || cmdText.startsWith('clean ') ||
-                cmdText.startsWith('restart') || cmdText === 'fix' || cmdText === 'clean';
-            if (isFixCommand) {
-                (async () => {
-                    try {
-                        const handled = await fixCommandHandler(topicId, text);
-                        if (!handled) {
-                            // Not a recognized fix command — fall through to session routing
-                            // Re-trigger the normal routing by calling the topic message handler again
-                            // Actually, since we can't re-trigger, just send a help message
-                            await telegram.sendToTopic(topicId, `I didn't recognize that command. Available fix commands:\n` +
-                                `• "fix auth" — Generate an API security token\n` +
-                                `• "fix lifeline" — Restart the crash-recovery system\n` +
-                                `• "fix shadow" — Remove shadow installation\n` +
-                                `• "clean processes" — Kill external Claude processes\n` +
-                                `• "restart" — Restart the server\n` +
-                                `• "restart sessions" — Restart stuck sessions`);
-                        }
-                    }
-                    catch (err) {
-                        console.error(`[telegram] Fix command error:`, err);
-                        await telegram.sendToTopic(topicId, `Something went wrong while trying to fix that: ${err instanceof Error ? err.message : String(err)}`).catch(() => { });
+        //
+        // These ONLY apply in the Agent Attention topic. Scoping the gate there
+        // (shouldInterceptFixCommand) is deliberate: previously the verb test ran
+        // in every topic, so a message starting with restart/fix/clean in a normal
+        // conversation was swallowed and bounced back with an "I didn't recognize
+        // that command" help list — which is exactly why typing "restart sessions"
+        // in a stuck session's own topic never reached the session. Outside the
+        // attention topic the message now falls through to session routing below.
+        if (fixCommandHandler && shouldInterceptFixCommand(text, topicId, getAttentionTopicId?.())) {
+            (async () => {
+                try {
+                    const handled = await fixCommandHandler(topicId, text);
+                    if (!handled) {
+                        // In the attention topic, but not a recognized fix command — show help.
+                        await telegram.sendToTopic(topicId, `I didn't recognize that command. Available fix commands:\n` +
+                            `• "fix auth" — Generate an API security token\n` +
+                            `• "fix lifeline" — Restart the crash-recovery system\n` +
+                            `• "fix shadow" — Remove shadow installation\n` +
+                            `• "clean processes" — Kill external Claude processes\n` +
+                            `• "restart" — Restart the server\n` +
+                            `• "restart sessions" — Restart stuck sessions`);
                     }
-                })();
-                return;
-            }
+                }
+                catch (err) {
+                    console.error(`[telegram] Fix command error:`, err);
+                    await telegram.sendToTopic(topicId, `Something went wrong while trying to fix that: ${err instanceof Error ? err.message : String(err)}`).catch(() => { });
+                }
+            })();
+            return;
         }
         // ── Pipeline-typed routing ──────────────────────────────────────
         // Convert to PipelineMessage — types enforce that sender identity
@@ -3717,7 +3751,7 @@ export async function startServer(options) {
             // reached the AI session as plain chat text.
             const userManagerSendOnly = new UserManager(config.stateDir, config.users);
             _fixDeps = { state, liveConfig, sessionManager, telegram, config };
-            wireTelegramRouting(telegram, sessionManager, quotaTracker, topicMemory, userManagerSendOnly, (topicId, text) => handleFixCommand(topicId, text, _fixDeps), () => (collaborationSurfacer && conversationStore && telegram) ? { collaborationSurfacer, conversationStore, commitmentTracker, telegram, brief: briefDeps } : null, () => _agentServerRef?.getTopicOperatorStore() ?? null);
+            wireTelegramRouting(telegram, sessionManager, quotaTracker, topicMemory, userManagerSendOnly, (topicId, text) => handleFixCommand(topicId, text, _fixDeps), () => (collaborationSurfacer && conversationStore && telegram) ? { collaborationSurfacer, conversationStore, commitmentTracker, telegram, brief: briefDeps } : null, () => _agentServerRef?.getTopicOperatorStore() ?? null, () => state.get('agent-attention-topic'));
             wireTelegramCallbacks(telegram, sessionManager, state, quotaTracker, undefined, config.sessions.claudePath, topicMemory);
             console.log(pc.green('  Telegram routing + command callbacks wired (send-only)'));
         }
@@ -3843,7 +3877,7 @@ export async function startServer(options) {
                 config,
             };
             // Wire up topic → session routing and session management callbacks
-            wireTelegramRouting(telegram, sessionManager, quotaTracker, topicMemory, userManager, (topicId, text) => handleFixCommand(topicId, text, _fixDeps), () => (collaborationSurfacer && conversationStore && telegram) ? { collaborationSurfacer, conversationStore, commitmentTracker, telegram, brief: briefDeps } : null, () => _agentServerRef?.getTopicOperatorStore() ?? null);
+            wireTelegramRouting(telegram, sessionManager, quotaTracker, topicMemory, userManager, (topicId, text) => handleFixCommand(topicId, text, _fixDeps), () => (collaborationSurfacer && conversationStore && telegram) ? { collaborationSurfacer, conversationStore, commitmentTracker, telegram, brief: briefDeps } : null, () => _agentServerRef?.getTopicOperatorStore() ?? null, () => state.get('agent-attention-topic'));
             wireTelegramCallbacks(telegram, sessionManager, state, quotaTracker, accountSwitcher, config.sessions.claudePath, topicMemory);
             // Wire up unknown-user handling (Multi-User Setup Wizard Phase 4.5)
             telegram.onGetRegistrationPolicy = () => ({
@@ -4300,6 +4334,40 @@ export async function startServer(options) {
                 catch (e) {
                     console.warn('[slack] permission gate wiring skipped:', e.message);
                 }
+                // ── Ambient "should I speak?" gate (considered/ambient mode, §5.2) — DARK ──
+                // Attached ONLY when at least one channel is explicitly opted into proactive
+                // contribution (`ambientContribution.enabledChannelIds` non-empty). With no
+                // such config, no gate is attached and undirected messages drop exactly as
+                // today (mention-only). The gate can only ever make the agent quieter
+                // (fail-to-silence): no LLM provider / error / low confidence / rate-limit →
+                // stay silent.
+                try {
+                    const slackCfg = slackConfig.config;
+                    const amCfg = slackCfg.ambientContribution;
+                    if (amCfg && Array.isArray(amCfg.enabledChannelIds) && amCfg.enabledChannelIds.length > 0) {
+                        const { AmbientContributionGate } = await import('../permissions/index.js');
+                        const ambientGate = new AmbientContributionGate({
+                            config: {
+                                enabledChannelIds: amCfg.enabledChannelIds,
+                                maxProactivePerChannel: amCfg.maxProactivePerChannel,
+                                windowMs: amCfg.windowMs,
+                                minConfidence: amCfg.minConfidence,
+                            },
+                            // No provider ⇒ the gate stays silent for every message (fail-to-silence).
+                            intelligence: sharedIntelligence ?? undefined,
+                            onDecision: (decision, channelId) => {
+                                if (decision.speak) {
+                                    console.log(`[slack] ambient gate: SPEAK in ${channelId} (${decision.reason})`);
+                                }
+                            },
+                        });
+                        slackAdapter.setAmbientGate(ambientGate);
+                        console.log(`[slack] ambient contribution gate attached for ${amCfg.enabledChannelIds.length} channel(s)${sharedIntelligence ? '' : ' (no LLM provider — gate stays silent)'}`);
+                    }
+                }
+                catch (e) {
+                    console.warn('[slack] ambient gate wiring skipped:', e.message);
+                }
                 // Wire message handler — inject Slack messages into sessions
                 slackAdapter.onMessage(async (message) => {
                     const channelId = message.channel.identifier;