instar 1.3.444 → 1.3.445

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.444",
+  "version": "1.3.445",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-09T10:00:34.029Z",
-  "instarVersion": "1.3.444",
+  "generatedAt": "2026-06-09T17:12:42.642Z",
+  "instarVersion": "1.3.445",
   "entryCount": 199,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.445.md

@@ -0,0 +1,99 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Scopes the emergency "fix command" gate to the **Agent Attention topic** so it can no longer swallow ordinary messages in other topics. The gate in `wireTelegramRouting` (`src/commands/server.ts`) used to intercept any message starting with `restart`, `fix `, or `clean ` in **every** topic, hand it to `handleFixCommand`, and `return` — but `handleFixCommand` only does anything in the Agent Attention topic and returns `false` everywhere else. So in a normal topic the message was bounced back with *"I didn't recognize that command. Available fix commands: …"* (a list that even advertised "restart sessions" as valid) **and never routed to the session**. A user typing "restart sessions" to revive a stuck session in that session's own topic was hit by exactly this: the gate ate the message. The decision is now a pure, unit-tested helper `shouldInterceptFixCommand(text, topicId, attentionTopicId)` that returns true only inside the attention topic; `wireTelegramRouting` resolves the attention topic via a late-bound `getAttentionTopicId` and both call sites pass it. Outside the attention topic the message falls through to normal session routing — including plain phrases like "restart the build" or "fix the login page" that were silently eaten before.
+
+## What to Tell Your User
+
+If you ever messaged a session something starting with "restart", "fix", or "clean" — including trying to revive a stuck session by typing "restart sessions" — and got a confusing *"I didn't recognize that command"* reply (with a list that literally showed the command you typed), that message was being intercepted and never reached the session. That's fixed: those messages now go through to the session like any other. The "fix command" shortcuts (restart, fix auth, clean processes, …) still work — they just only apply in the Agent Attention topic, which is where I post the notifications you tap to resolve.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Fix-command shortcuts scoped to the Agent Attention topic | unchanged — tap/reply in the Attention topic; everywhere else your message reaches the session |
+| Ordinary "restart/fix/clean …" messages reach the session | just send them normally in any session topic |
+
+## Evidence
+
+Reproduction (live, 2026-06-09, topic 21624 "initiatives and maturation check-ins"): the user typed `restart sessions` to unstick a session and got *"I didn't recognize that command. Available fix commands: … • restart sessions — Restart stuck sessions"* — the gate swallowed the message (no `restart sessions` ever appeared in the session's tmux pane) while listing the exact command as valid. Root cause traced in code: the gate's `isFixCommand` verb test ran in all topics and `return`ed after `handleFixCommand` (which guards on `topicId === agent-attention-topic` and returns `false` otherwise).
+
+After the fix: new unit suite `tests/unit/fix-command-routing.test.ts` (17 tests) pins both sides of the boundary — in the attention topic every fix verb intercepts (and verb-lookalikes "fixture"/"cleanup" do not), while in a non-attention topic "restart sessions", "restart the build", "fix the login page", "clean up this function" all return `false` (fall through to the session); a null/undefined attention topic never intercepts. `tsc --noEmit` clean; the full set of unit tests importing `commands/server` (38 files, 364 tests) green.
+
+## The problem
+
+You sent a session a message to wake it up — "restart sessions" — and instead
+of doing anything, I replied *"I didn't recognize that command"* and showed you
+a list of commands that literally included "restart sessions." That's
+maddening: I rejected the exact thing I told you to type. Worse, your message
+never actually reached the session at all.
+
+Here's what was really happening under the hood.
+
+I have a set of emergency "fix command" shortcuts — short things you can type
+like "restart", "fix auth", "clean processes" — that I handle directly without
+spinning up a whole AI session. They exist for one specific place: the **Agent
+Attention topic**, where I post little "something needs fixing, tap to resolve"
+notifications. In that topic, typing "restart" should just work.
+
+The bug: the code that *catches* those shortcut words was running in **every
+topic**, not just the Attention topic. So any message you sent that happened to
+start with "restart", "fix ", or "clean " got grabbed by the shortcut-catcher
+first. The catcher then asked the real handler to run it — but the real handler
+checks "am I in the Attention topic?" and, if not, quietly says "not mine" and
+does nothing. At that point the catcher gave up with the confusing "I didn't
+recognize that command" message **and threw your message away** — it never got
+passed along to the session you were actually talking to.
+
+So two everyday things were broken:
+1. Trying to revive a stuck session by typing "restart sessions" in that
+   session's own topic — eaten, with a misleading reply.
+2. Just talking normally — "restart the build", "fix the login page", "clean up
+   this function" — anything that started with one of those words got silently
+   swallowed instead of reaching the session.
+
+## What already exists
+
+- The fix-command shortcuts ("restart", "fix auth", etc.) and the handler that
+  runs them. These were already correctly limited to the Attention topic *on
+  the execution side* — the handler refuses to act anywhere else.
+- The normal path that routes a message to its session. That path was always
+  there; the shortcut-catcher was just jumping in front of it and stopping it.
+
+## What's new
+
+One small, surgical change: the shortcut-catcher now checks **which topic it's
+in before grabbing the message.** It only intercepts inside the Agent Attention
+topic. Everywhere else, the message flows straight through to the session like
+any other message.
+
+The check is a tiny pure function, `shouldInterceptFixCommand(text, topicId,
+attentionTopicId)`, that returns "yes, intercept" only when the message is in
+the Attention topic AND looks like a fix command. It's covered by 17 unit tests
+that nail down both sides: in the Attention topic the shortcuts still fire (and
+lookalike words like "fixture" or "cleanup" correctly don't); in any other
+topic, "restart sessions" and friends fall through to the session.
+
+## The safeguards in plain terms
+
+- **Nothing is removed.** The fix-command shortcuts still work exactly as
+  before — they were always Attention-topic-only on the execution side; now the
+  catching side agrees. So no real capability is lost.
+- **Fail-safe default.** If I don't yet know which topic is the Attention topic
+  (e.g. very early at startup), the catcher simply doesn't intercept — messages
+  go to the session. That's the safe direction: route, don't swallow.
+- **It only makes the gate *less* aggressive.** This change can only let more
+  messages through to sessions; it can never block a message that wasn't already
+  being blocked. That's why the risk is low.
+
+## What you need to decide
+
+Nothing complicated. This is a bug fix that makes your messages reliably reach
+your sessions. The only judgment call is whether to ship it as a normal patch
+(yes) — there's no new setting to configure and no behavior you have to opt
+into. After it deploys, "restart sessions" (and ordinary chat starting with
+restart/fix/clean) will reach the session instead of being eaten.

package/upgrades/side-effects/fixcommand-gate-nonattention-fallthrough.md

@@ -0,0 +1,93 @@
+# Side-Effects Review — Scope the fix-command gate to the Agent Attention topic
+
+**Version / slug:** `fixcommand-gate-nonattention-fallthrough`
+**Date:** `2026-06-09`
+**Author:** `Instar Agent (echo)`
+**Second-pass reviewer:** `independent reviewer subagent — concurred`
+
+## Summary of the change
+
+The emergency "fix command" gate in `wireTelegramRouting` (`src/commands/server.ts`) intercepted any inbound Telegram message whose text started with `restart`, `fix `, or `clean ` in **every** topic, dispatched it to `handleFixCommand`, and unconditionally `return`ed. But `handleFixCommand` only executes in the Agent Attention topic (`topicId === state.get('agent-attention-topic')`) and returns `false` everywhere else — so in a non-attention topic the gate sent the user an "I didn't recognize that command" help list **and swallowed the message** (it never reached the session). This change introduces a pure, exported helper `shouldInterceptFixCommand(text, topicId, attentionTopicId)` that returns true only when the message is in the Agent Attention topic and matches a fix verb. `wireTelegramRouting` gains a late-bound `getAttentionTopicId?: () => number | null | undefined` parameter; both call sites pass `() => state.get<number>('agent-attention-topic')`. The gate now fires only when `shouldInterceptFixCommand(...)` is true; otherwise the message falls through to normal session routing. Files: `src/commands/server.ts` (helper + signature + gate + 2 call sites), `tests/unit/fix-command-routing.test.ts` (new).
+
+## Decision-point inventory
+
+- `wireTelegramRouting` fix-command gate (`src/commands/server.ts`, inbound Telegram dispatch) — **modify** — the gate that decides whether a message is handled as a server-side fix command (and swallowed) vs routed to the session. Previously gated on a topic-agnostic verb test; now gated on `shouldInterceptFixCommand` which additionally requires the Agent Attention topic.
+- `handleFixCommand`'s internal attention-topic guard (lines ~186) — **pass-through (kept)** — retained as defense-in-depth; it still returns `false` outside the attention topic, so even if the gate ever fired in the wrong topic nothing would execute.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+This change strictly *reduces* blocking. Before: any message starting with `restart`/`fix `/`clean ` in a non-attention topic was swallowed (over-blocked). After: those messages route to the session. Inside the Agent Attention topic the behavior is unchanged. There is no new input that is now rejected that previously was accepted — the change can only let *more* messages through. So: no new over-block introduced; an existing over-block (the core bug) is removed.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+Within the Agent Attention topic, the verb test is still a brittle prefix match (`startsWith('restart')`, etc.). A user in the Attention topic typing a non-command sentence that happens to start with "restart"/"fix "/"clean " (e.g. "restart the build") will still get the "I didn't recognize that command" help instead of being treated as chat. This is unchanged from before and is acceptable: the Attention topic is a control surface for tapping notifications, not a general chat thread, and `handleFixCommand` already only acts on the exact known commands. We are deliberately not widening or narrowing the in-attention-topic verb matching in this change (single-responsibility: fix the topic-scoping bug only). No tracked deferral — the in-topic verb matching is correct for its purpose, not an omission.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. The routing decision belongs exactly where the gate sits — at the inbound message dispatch in `wireTelegramRouting`, before session routing. The change extracts the *decision* into a pure function (`shouldInterceptFixCommand`) at the same layer, which is the right altitude: it is a cheap, deterministic predicate, not a reasoning task, and it now consumes the same `agent-attention-topic` state that `handleFixCommand` already used as its own guard — so the gate and the handler now agree on the same authority (the attention topic) instead of the gate being topic-blind. No higher-level (LLM) gate is warranted: "is this the attention topic and a known verb" is objective.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change has no NEW block/allow surface; it *narrows* an existing brittle authority so it no longer over-reaches.
+
+The fix-command gate is a brittle (prefix-match) detector that holds blocking authority (it swallows the message). Per the signal-vs-authority principle, a brittle detector must not over-extend its blocking authority. This change does the principle-compliant thing: it constrains that brittle authority to the one topic where the action is actually valid (the Agent Attention control topic), and removes its authority everywhere else (fall through to session). It does not add new brittle blocking authority; it shrinks existing brittle blocking authority to its legitimate scope. No reshaping needed.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** The gate runs after the slash-command handler and the threadline hub-command intercept, and before the pipeline/session routing. Previously it *shadowed* session routing for any restart/fix/clean-prefixed message in every topic. After this change it only shadows session routing in the Agent Attention topic — which is correct, since fix commands there are not meant to spawn a session. No other check is newly shadowed.
+- **Double-fire:** No. The gate `return`s on intercept (only in the attention topic now), so a message is either handled as a fix command OR routed to the session, never both. `handleFixCommand`'s own attention guard prevents double execution even if the gate condition were wrong.
+- **Races:** The new param is a synchronous getter over `StateManager.get` (the same in-memory/JSON state the rest of routing reads). No new shared mutable state is introduced; `getAttentionTopicId` only reads.
+- **Feedback loops:** None. The predicate reads state and returns a boolean; it feeds nothing back.
+
+---
+
+## 6. External surfaces
+
+- **Other agents / users:** This is instar source shipped to the whole install base. User-visible effect is strictly positive: messages starting with restart/fix/clean now reach the session in normal topics. The "I didn't recognize that command" reply will no longer appear in non-attention topics (it remains in the Attention topic for genuinely unknown commands).
+- **External systems:** No change to Telegram API usage, payloads, or the fix-command actions themselves (restart/clean/etc. behave identically when invoked in the Attention topic).
+- **Persistent state:** None. No new state keys, ledgers, or migrations. Reads the existing `agent-attention-topic` key only.
+- **Timing/runtime:** If `agent-attention-topic` isn't set yet (early boot), the getter returns null/undefined and the gate simply doesn't intercept — messages route to the session. Safe direction.
+
+---
+
+## 7. Rollback cost
+
+Pure code change, no persistent state, no migration. Back-out = revert the commit and ship the next patch; behavior returns to the prior (buggy) state with no cleanup. No agent-state repair, no data migration. During the rollback window users would simply see the old swallow-and-bounce behavior again. Low rollback cost.
+
+## Conclusion
+
+The review confirms this is a scope-narrowing fix to a brittle blocking authority: it removes an over-block (the core bug — messages swallowed in non-attention topics) and adds no new blocking surface. The decision is extracted into a pure, fully unit-tested predicate, and the gate now agrees with the handler's own attention-topic guard. No design changes were required by the review. Because the change touches inbound message dispatch, a Phase-5 second-pass review is required before commit.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** independent reviewer subagent (general-purpose)
+**Independent read of the artifact: concur**
+
+Concur with the review. The reviewer independently verified: (1) the boundary — `shouldInterceptFixCommand` returns false for null/undefined attention topic and for any non-attention topic, true only in the attention topic with a matching verb, and the verb clause is byte-identical to the old inline test (no in-topic regression); (2) BOTH `wireTelegramRouting` call sites (server.ts:4062-4066 send-only and 4203-4207 full) pass the `() => state.get<number>('agent-attention-topic')` resolver — no path left on old behavior; (3) no new swallow/double-fire — the gate `return`s only on intercept, normal routing sits immediately below, and `handleFixCommand`'s internal attention guard is harmless redundant defense; (4) signal-vs-authority — strictly narrows existing brittle blocking authority, adds no new block surface. Additional checks: `wireWhatsAppRouting` has no parallel fix-command gate (no missed surface); the stuck-message replay path re-injects through the same handler so it inherits the corrected boundary; existing test callers omit the new optional arg safely (null-safe getter). One non-blocking observation: new coverage is unit-only (the pure predicate, both sides) — proportionate since this adds no API route or DI component; wiring verified correct by inspection.
+
+---
+
+## Evidence pointers
+
+- Live reproduction: 2026-06-09, topic 21624 — user typed `restart sessions`, received the "I didn't recognize that command" help list (which advertised "restart sessions"), and the text never appeared in the session's tmux pane.
+- Tests: `tests/unit/fix-command-routing.test.ts` (17 tests, both sides of the boundary). `tsc --noEmit` clean; 364 unit tests across the 38 files importing `commands/server` green.