instar 1.3.355 → 1.3.357

package/upgrades/side-effects/topic-operator-autobind-inc2d.md

@@ -0,0 +1,70 @@
+# Side-effects review — Topic Operator inbound auto-bind (Know Your Principal #898, increment 2d)
+
+## What this change does
+The WRITE side of the operator binding. On the lifeline-forward inbound path
+(`POST /internal/telegram-forward`), the verified operator of a topic is now
+recorded automatically from the AUTHENTICATED + AUTHORIZED sender of a real user
+message — so the session-start hook (#908) and the future cross-principal guard
+have a populated binding instead of relying on a manual `POST /topic-operator`.
+
+- `TelegramAdapter`: new public `isAuthorizedSender(number|string): boolean`,
+  wrapping the private `isAuthorized` (number/string tolerant; blank/non-numeric
+  → false). Read-only; no behavior change to the private path.
+- `routes.ts` `/internal/telegram-forward`: one additive block, placed AFTER the
+  a2a-hook short-circuit and BEFORE `onTopicMessage`, that binds the operator iff
+  `ctx.telegram.isAuthorizedSender(fromUserId)` is true.
+
+## The load-bearing security property
+ONLY an authorized sender becomes the operator. An unauthorized party in the
+bot's group is never seated — that is exactly the cross-principal ("Caroline")
+bug, and the integration test proves the over-the-wire refusal (a `fromUserId`
+outside the allowlist, even with `fromFirstName: "Caroline"`, binds nothing).
+The uid is the platform-authenticated sender id; a content name is never the
+source (`TopicOperatorStore.setOperator` enforces this by construction, #904).
+
+## Blast radius (hot path — reviewed carefully)
+- **Additive + fail-soft.** The block is wrapped in try/catch and only runs when
+  `ctx.topicOperatorStore` is non-null, `fromUserId` is present, and `topicId` is
+  a number. Any error is logged and swallowed — an auto-bind failure can NEVER
+  break message routing. `setOperator` is a fast local JSON write, idempotent on
+  the same uid (a redelivered message re-binds the same operator harmlessly).
+- **a2a-safe.** Placed after the a2a short-circuit, so agent-to-agent bot messages
+  return before the bind; a bot id is also not in `authorizedUserIds` anyway. The
+  14 existing `/internal/telegram-forward` integration tests stay green (no
+  regression to the version handshake, exactly-once, sentinel, or a2a paths).
+- **No new route / class / config key / dependency.** It consumes the store +
+  routes shipped in #904/#906 and the injection from #908.
+
+## No-allowlist trust model (documented)
+`isAuthorizedSender` mirrors `isAuthorized`: with NO `authorizedUserIds` allowlist
+configured, every authenticated sender is accepted (the agent already serves
+everyone in that mode), so the operator becomes the most-recent authenticated
+sender. This is consistent with the existing trust model and is NOT a
+Caroline-class bleed (the uid is Telegram-authenticated, not a content name). A
+secure deployment configures `authorizedUserIds`, and then only those uids bind.
+
+## Scope (deliberate) + the known gap
+This binds on the **lifeline-forward path only** — the instar fleet's primary
+inbound route. The adapter's own long-poll path (`onTopicMessage`, the
+no-lifeline case) is NOT covered here, because its single shared callback is
+defined in `src/commands/server.ts` (the production composition root, not
+route-testable). That gap is tracked for a follow-up (Inc-2e): bind in the shared
+`onTopicMessage` handler to cover both paths with one change. Until then, a
+no-lifeline install simply has no auto-bind (fail-safe: no binding → no injection
+→ no false identity), and `POST /topic-operator` remains the manual path.
+
+## Migration parity
+None required — server-side route behavior + an in-process adapter method reach
+existing agents on the next server update (the Migration Parity Standard governs
+agent-installed FILES; this touches none).
+
+## Tests
+- Tier 1 (unit): `tests/unit/telegram-isauthorizedsender.test.ts` (5) — both sides
+  of the boundary, number/string ids, blank/NaN guard, no-allowlist model.
+- Tier 2 (integration): `tests/integration/topic-operator-autobind-route.test.ts`
+  (4) — over the wire: authorized binds, unauthorized doesn't, a2a bot doesn't,
+  null store no-op. Existing telegram-forward suites (14) stay green.
+
+## Rollback
+Revert the one route block + the `isAuthorizedSender` method + delete the two
+tests. The store on disk is inert without the bind.

package/upgrades/side-effects/topic-operator-hook-injection-inc2c.md

@@ -0,0 +1,79 @@
+# Side-effects review — Topic Operator session-start injection (Know Your Principal #898, increment 2c)
+
+## What this change does
+Adds one fetch-block to the generated `session-start` hook
+(`PostUpdateMigrator.getHookContent('session-start')`) that injects the
+`<topic-operator>` block at session boot — the READ side of the operator binding
+shipped in #904 (store) and #906 (routes). When a topic has a verified operator,
+the agent now reasons with it from message one.
+
+## Blast radius
+- **One template string edit, additive.** The block is appended after the
+  existing ORG-INTENT and AUTO-LEARNED-PREFERENCES injection blocks and before the
+  SESSION-BOOT-SELF-KNOWLEDGE block — modeled byte-for-byte on those two
+  precedents (same `curl -sf --max-time 4` + `python3` present/block parse + echo).
+- **Fail-open, three guards.** The block only runs when `$INSTAR_TELEGRAM_TOPIC`
+  AND `$PORT` AND `$TOKEN` are all set. `curl -sf` emits nothing on any non-2xx
+  (route 503 when the store is unavailable, or `{present:false}` for an unbound
+  topic), so an unbound topic or an old server injects nothing — the session
+  continues normally. A non-Telegram session (no topic env) skips entirely.
+- **No new route, class, config key, or dependency.** It consumes the
+  `/topic-operator/session-context` route that already shipped in #906.
+- **Bearer token stays in the header** (never the URL/query), matching the other
+  injection blocks.
+
+## The security property
+The injected block names the operator established ONLY from the platform-verified
+sender id (the store guarantees this by construction — #904). The hook merely
+surfaces that verified binding; it cannot itself seat anyone. So this read-side
+change cannot introduce a Caroline-class identity bleed — it can only make the
+ALREADY-verified operator visible to the agent at boot.
+
+## Compaction parity (constitutional)
+The same fetch is ALSO wired into `getCompactionRecovery()` — its compaction twin —
+so the verified operator is re-injected after a context reset, not presumed to
+survive in the compaction summary (the `session-context-compaction-parity` standard
+from PR #811, enforced by `tests/unit/session-context-compaction-parity.test.ts`).
+This is thematically load-bearing for Know Your Principal: an agent that loses its
+verified-operator awareness post-compaction is exactly the identity gap this feature
+closes. The twin block mirrors the SESSION-BOOT-SELF-KNOWLEDGE re-injection
+precedent (own `TOPIC_OP_PORT`/`TOPIC_OP_TOKEN` resolution, same fail-open contract),
+and the injector is NOT added to the parity allowlist (the allowlist only shrinks).
+
+## Migration parity
+The `session-start` hook lives in the always-overwritten `instar/` hook set:
+`migrateHooks()` rewrites `hooks/instar/session-start.sh` from
+`getSessionStartHook()` on EVERY update run (PostUpdateMigrator.ts:1958). So this
+block reaches existing agents automatically on their next update — no dedicated
+migration needed, and the migration-parity-hooks unit suite stays green.
+
+## Agent awareness (deliberately deferred)
+No CLAUDE.md template section is added in this increment. The injected
+`<topic-operator>` block is self-describing (it carries its own "do not attribute
+to any other name" instruction), and the governing behavior is already in the
+ratified #898 "Know Your Principal" constitution standard. The operator-binding
+feature's agent-awareness capability section will be added ONCE, as a coherent
+whole, when the feature is end-to-end (after the Inc-2d inbound auto-bind and the
+Inc-3 guard) — rather than fragmenting it across increments. The feature-delivery
+and docs-coverage gates pass without it.
+
+## Framework generality
+Framework-agnostic. The block is emitted into the generic session-start hook that
+every framework's session runs; the `<topic-operator>` payload is plain text any
+harness injects. The topic is resolved from `$INSTAR_TELEGRAM_TOPIC`, the same env
+the existing topic-context block uses — not coupled to Claude Code, Codex, or
+Gemini.
+
+## Tests
+- Tier 3 (E2E): `tests/e2e/topic-operator-hook-injection-lifecycle.test.ts` (3) —
+  Phase 1 asserts the generated hook SOURCE wires the fetch; Phase 2 extracts the
+  exact block and runs it against a LIVE server, proving it emits the
+  `<topic-operator>` block when a topic is bound and nothing when unbound.
+- Tier 1/2 for the store + route shipped in #904/#906; the analog hook suites
+  (PostUpdateMigrator-bootSelfKnowledge, migration-parity-hooks,
+  OrgIntentManager-session-start-format) stay green.
+
+## Rollback
+Revert the single template-string block in PostUpdateMigrator.ts + delete the E2E
+test. The next update rewrites the hook without the block; nothing else depends
+on it.

package/upgrades/topic-operator-autobind-inc2d.eli16.md

@@ -0,0 +1,46 @@
+# ELI16 — Automatically remembering who the boss is
+
+## The one-sentence version
+When the verified boss sends a message, the agent now automatically writes down
+"this is the boss of this chat" — so it no longer has to be told by hand.
+
+## The backstory
+We've been fixing a real problem: an agent on a shared computer slowly started
+treating a *different real person* (call her Caroline) as its boss, because the
+mix-up lived inside the agent's own writing where nothing was watching. To fix it
+we built three pieces:
+
+1. A filing cabinet that remembers, per chat, who the verified boss is — and the
+   rule is strict: the boss is decided ONLY by the verified ID of whoever actually
+   sent the message, never a name typed in a document.
+2. A startup note that hands the agent that "who's your boss" info when it wakes
+   up (shipped last step).
+3. **This step:** actually filling in the filing cabinet automatically.
+
+## What this change adds
+Before, the filing cabinet only got filled in by a manual one-time call. Now,
+whenever a message comes in through the agent's main message pipe, the system
+checks: "is this sender on the allowed list?" If yes, it quietly writes them down
+as the verified boss of that chat. If no, it does NOTHING — an outsider in the
+group can never become the boss. That "only allowed senders count" rule is the
+whole point: it's what stops the Caroline mix-up from happening again. We prove it
+with a test that sends a message from an *un*-allowed person literally named
+"Caroline" and checks that nobody gets written down.
+
+## Why it's safe
+- It only **adds** a step, wrapped so that if anything ever goes wrong, the message
+  still gets handled normally — recording the boss can never break the chat.
+- It ignores robot-to-robot messages (those get handled earlier), and it ignores
+  anyone not on the allowed list.
+- Writing the same boss twice is harmless, so a re-delivered message can't cause
+  trouble.
+
+## What's deliberately left for next time
+This fills in the cabinet on the agent's **main** message pipe (the one the whole
+fleet uses). There's a second, simpler pipe (used when the agent talks to Telegram
+directly without the relay) that this step doesn't cover yet, because that one's
+wiring lives in a harder-to-test startup file. That's tracked as a small follow-up.
+Until then, an agent on that simpler setup just doesn't auto-fill the cabinet —
+which is safe, because no entry means no false boss. The final step after that
+lets the agent's own safety checker USE the binding to catch itself if it ever
+credits a decision to the wrong person.

package/upgrades/topic-operator-hook-injection-inc2c.eli16.md

@@ -0,0 +1,47 @@
+# ELI16 — Telling the agent who its boss is, the moment it wakes up
+
+## The one-sentence version
+When the agent starts a conversation, it now gets handed a little note that says
+"the verified boss of this chat is X" — so it knows from the very first message
+who it's working for, instead of guessing from names it reads later.
+
+## The backstory
+We've been fixing a real problem: an agent on a shared computer slowly started
+treating a *different real person* (call her Caroline) as its boss, because the
+mix-up lived inside the agent's own writing where nothing was watching. To fix it
+we built three pieces:
+
+1. A filing cabinet (`TopicOperatorStore`) that remembers, per conversation, who
+   the verified boss is — and the rule is strict: the boss is decided ONLY by the
+   verified ID of whoever actually sent the message, never by a name typed in a
+   document.
+2. Four web endpoints to read and set that binding (shipped last step).
+3. **This step:** actually handing the agent that "who's your boss" note at the
+   start of every conversation.
+
+## What this change adds
+At session start, the agent already gets handed a few notes — the company's rules,
+the preferences it has learned about you, and so on. This change adds one more
+note to that pile: it quietly asks the server "who's the verified boss of this
+chat?" and, if there's an answer, prints a short block telling the agent. The
+block also reminds the agent: don't ever swap in some other name you happen to
+read — an unfamiliar name in the boss's chair is a question to resolve, not a fact
+to accept.
+
+## Why it's safe
+- It only **adds** a note; it changes nothing else about how sessions start.
+- It's careful: it only runs if there's actually a chat topic and the server is
+  reachable. If the server can't answer, or nobody's been set as boss yet, it
+  prints nothing and the session goes on exactly as before.
+- It can't *make* anyone the boss — it only shows the boss who was already
+  verified the safe way. So there's no way for this to repeat the Caroline mix-up.
+- Every agent gets it automatically the next time it updates, because this note
+  lives in the startup script that always gets refreshed on update.
+
+## What's still coming
+Right now a boss gets recorded either by a one-time manual call, or — in the next
+step — automatically whenever the verified boss sends a message. After that, a
+final step will let the agent's own safety checker USE this binding to catch
+itself if it ever credits a decision to the wrong person. This step is the
+"agent can SEE its boss" piece; the "agent gets corrected if it forgets" piece
+comes next.