instar 1.3.355 → 1.3.356

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.355",
+  "version": "1.3.356",
   "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-06T08:02:23.000Z",
-  "instarVersion": "1.3.355",
+  "generatedAt": "2026-06-06T08:09:49.249Z",
+  "instarVersion": "1.3.356",
   "entryCount": 199,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "aa88c10ba4816114371a58fa15df8d18a92580fbb861c2c3007cab4a85d5e4d2",
+      "contentHash": "b8227d4a75bfe3ca1a9d0fee53580167a5dbc4e67fe458af11ae66aed1a1d0a0",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "aa88c10ba4816114371a58fa15df8d18a92580fbb861c2c3007cab4a85d5e4d2",
+      "contentHash": "b8227d4a75bfe3ca1a9d0fee53580167a5dbc4e67fe458af11ae66aed1a1d0a0",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "aa88c10ba4816114371a58fa15df8d18a92580fbb861c2c3007cab4a85d5e4d2",
+      "contentHash": "b8227d4a75bfe3ca1a9d0fee53580167a5dbc4e67fe458af11ae66aed1a1d0a0",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "aa88c10ba4816114371a58fa15df8d18a92580fbb861c2c3007cab4a85d5e4d2",
+      "contentHash": "b8227d4a75bfe3ca1a9d0fee53580167a5dbc4e67fe458af11ae66aed1a1d0a0",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "aa88c10ba4816114371a58fa15df8d18a92580fbb861c2c3007cab4a85d5e4d2",
+      "contentHash": "b8227d4a75bfe3ca1a9d0fee53580167a5dbc4e67fe458af11ae66aed1a1d0a0",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "aa88c10ba4816114371a58fa15df8d18a92580fbb861c2c3007cab4a85d5e4d2",
+      "contentHash": "b8227d4a75bfe3ca1a9d0fee53580167a5dbc4e67fe458af11ae66aed1a1d0a0",
       "since": "2025-01-01"
     },
     "hook:self-stop-guard": {
@@ -65,7 +65,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/self-stop-guard.js",
-      "contentHash": "aa88c10ba4816114371a58fa15df8d18a92580fbb861c2c3007cab4a85d5e4d2",
+      "contentHash": "b8227d4a75bfe3ca1a9d0fee53580167a5dbc4e67fe458af11ae66aed1a1d0a0",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -74,7 +74,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "aa88c10ba4816114371a58fa15df8d18a92580fbb861c2c3007cab4a85d5e4d2",
+      "contentHash": "b8227d4a75bfe3ca1a9d0fee53580167a5dbc4e67fe458af11ae66aed1a1d0a0",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -83,7 +83,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "aa88c10ba4816114371a58fa15df8d18a92580fbb861c2c3007cab4a85d5e4d2",
+      "contentHash": "b8227d4a75bfe3ca1a9d0fee53580167a5dbc4e67fe458af11ae66aed1a1d0a0",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "aa88c10ba4816114371a58fa15df8d18a92580fbb861c2c3007cab4a85d5e4d2",
+      "contentHash": "b8227d4a75bfe3ca1a9d0fee53580167a5dbc4e67fe458af11ae66aed1a1d0a0",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -101,7 +101,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "aa88c10ba4816114371a58fa15df8d18a92580fbb861c2c3007cab4a85d5e4d2",
+      "contentHash": "b8227d4a75bfe3ca1a9d0fee53580167a5dbc4e67fe458af11ae66aed1a1d0a0",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -110,7 +110,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "aa88c10ba4816114371a58fa15df8d18a92580fbb861c2c3007cab4a85d5e4d2",
+      "contentHash": "b8227d4a75bfe3ca1a9d0fee53580167a5dbc4e67fe458af11ae66aed1a1d0a0",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "aa88c10ba4816114371a58fa15df8d18a92580fbb861c2c3007cab4a85d5e4d2",
+      "contentHash": "b8227d4a75bfe3ca1a9d0fee53580167a5dbc4e67fe458af11ae66aed1a1d0a0",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -128,7 +128,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "aa88c10ba4816114371a58fa15df8d18a92580fbb861c2c3007cab4a85d5e4d2",
+      "contentHash": "b8227d4a75bfe3ca1a9d0fee53580167a5dbc4e67fe458af11ae66aed1a1d0a0",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "aa88c10ba4816114371a58fa15df8d18a92580fbb861c2c3007cab4a85d5e4d2",
+      "contentHash": "b8227d4a75bfe3ca1a9d0fee53580167a5dbc4e67fe458af11ae66aed1a1d0a0",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -146,7 +146,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "aa88c10ba4816114371a58fa15df8d18a92580fbb861c2c3007cab4a85d5e4d2",
+      "contentHash": "b8227d4a75bfe3ca1a9d0fee53580167a5dbc4e67fe458af11ae66aed1a1d0a0",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1538,7 +1538,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "aa88c10ba4816114371a58fa15df8d18a92580fbb861c2c3007cab4a85d5e4d2",
+      "contentHash": "b8227d4a75bfe3ca1a9d0fee53580167a5dbc4e67fe458af11ae66aed1a1d0a0",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/upgrades/1.3.356.md

@@ -0,0 +1,38 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The `session-start` hook now injects the verified `<topic-operator>` block at
+session boot (Know Your Principal standard, security-build increment 2c). It
+fetches `/topic-operator/session-context?topicId=$INSTAR_TELEGRAM_TOPIC` (the route
+shipped in #906) and, when the topic has a verified operator, hands the agent a
+short block naming that operator — so the agent reasons with its authenticated
+principal from message one. This is the READ side of the operator binding; it
+cannot itself seat anyone (the store established the operator only from the
+platform-verified sender).
+
+## What to Tell Your User
+
+Nothing user-facing changes. Foundation wiring (experimental) for the Caroline
+identity-bleed security fix: the agent now SEES its verified operator at session
+start when one is bound, but no conversational behavior changes and nothing is
+gated. Auto-binding on inbound and the cross-principal guard are later increments.
+
+## Summary of New Capabilities
+
+- Session-start injection of the `<topic-operator>` block (fail-open: no topic /
+  unbound topic / store unavailable → nothing injected). Reaches existing agents
+  automatically — the `instar/` session-start hook is rewritten on every update.
+
+## Evidence
+
+Verified by 3 Tier-3 E2E lifecycle tests
+(`tests/e2e/topic-operator-hook-injection-lifecycle.test.ts`): 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. The analog hook suites
+(PostUpdateMigrator-bootSelfKnowledge, migration-parity-hooks,
+OrgIntentManager-session-start-format) stay green. Clean `tsc --noEmit`.

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-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.