instar 1.3.33 → 1.3.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.33",
+  "version": "1.3.35",
   "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-05-27T22:43:14.811Z",
-  "instarVersion": "1.3.33",
+  "generatedAt": "2026-05-27T23:05:08.677Z",
+  "instarVersion": "1.3.35",
   "entryCount": 192,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.34.md

@@ -0,0 +1,37 @@
+# Instar Upgrade Guide — NEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**TelegramAdapter can now run a second bot cleanly (groundwork for agent-to-agent Telegram
+comms).** Two internal additions, both shipping dark (nothing uses them yet): (1) a
+non-primary Telegram adapter can namespace its own state files under a sub-directory, so two
+bots in one process never clobber each other's poll-offset / registry / message-log /
+attention files; and (2) inbound Telegram messages now expose whether the sender is a bot
+(`is_bot`) and any `sender_chat` — the structural input a later update uses to tell an
+agent-sent message from a human typing the same text. The primary bot's behavior and state
+paths are byte-for-byte unchanged.
+
+## What to Tell Your User
+
+- Nothing changes in how your agent behaves today — this is plumbing for a later feature
+  (agents messaging each other over Telegram). Your agent's own Telegram keeps working
+  exactly as before.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Multi-instance `TelegramAdapter` | Internal — `new TelegramAdapter(cfg, stateDir, { subDir, suppressLifelineAutoCreate })`; primary (no opts) unchanged |
+| Sender-identity on inbound messages | Internal — `message.from.is_bot` + `message.sender_chat` exposed on the update type |
+
+## Evidence
+
+**Net-new groundwork, not a bug fix.** Proven by a dedicated test asserting the load-bearing
+safety property — a PRIMARY adapter's four state-file paths are byte-for-byte the historical
+`{stateDir}/...` values (this code runs the agent's own Telegram, so an unchanged primary is
+the non-negotiable invariant) — plus that a `subDir` adapter namespaces all four files and
+shares no path with the primary. The existing Telegram suites (71 tests across 5 files) pass
+unchanged as the regression guard. `tsc --noEmit` clean. The wiring that consumes these
+(the agent-message recipient handler + `sendAgentMessage`) lands in the follow-up PR.

package/upgrades/1.3.35.md

@@ -0,0 +1,44 @@
+# Instar Upgrade Guide — NEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Agent-to-agent Telegram comms primitive — send side now wired in.** Builds on the
+TelegramAdapter groundwork that landed in v1.3.34 (where the adapter learned to run a
+second bot cleanly + expose `is_bot`/`sender_chat` on inbound messages). This release adds
+the actual send function plus its safety machinery, still **dark** (no caller uses it
+yet — the mentor wires it in the follow-up):
+
+- **`sendAgentMessage`** — formats the visible `[a2a:from=… to=… role=… id=… corr=… ts=… v=1]`
+  marker, sends via an injected adapter, and writes one audit row for every outcome
+  (`ok` / `failed` / `role-refused`) — never silent.
+- **Runtime anti-loop guard** — refuses to send any role the caller wasn't constructed with
+  permission for. No marker formed, no send attempted, audit row written. This makes the
+  import-surface lint a backup rather than the only defense; the runtime guard always
+  applies. A role-handler that *consumes* role X structurally cannot *send* role X.
+- **Bot-token scrubbing on every error/audit surface** — Telegram 401 response bodies
+  sometimes echo the token; redaction makes leaks structurally impossible from this module.
+
+## What to Tell Your User
+
+- Nothing changes in how your agent behaves today — still plumbing. Your agent's own
+  Telegram keeps working exactly as before. A follow-up update wires this into the mentor
+  feature.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| `sendAgentMessage` + audit ledger | Internal — see `src/messaging/AgentTelegramComms.ts`; formats the marker, sends via injected adapter, writes a `SendAuditRow` for every outcome, scrubs the bot token |
+
+## Evidence
+
+**Net-new groundwork, not a bug fix.** Proven by 5 new unit tests (25 total in the suite,
+all green): happy-path send + audit (marker round-trips through `parseMarker` — sender output
+IS receiver input); correlation threading (explicit `correlationId` lands in the marker's
+`corr=` field for prompt↔reply linkage via Telegram chat history alone); the anti-loop
+role-refusal (a role not in the caller's allowed-set → no send, no marker, `role-refused`
+audit row); adapter failure with the bot token in the error body → token scrubbed from both
+the result reason and the audit row; `scrubToken` unit coverage across full-token,
+secret-portion, no-token-present, and undefined-token cases. `tsc --noEmit` clean.

package/upgrades/side-effects/agent-telegram-comms-send.md

@@ -0,0 +1,71 @@
+# Side-Effects Review — agent-to-agent Telegram comms: send side + audit (PR 2b)
+
+**Spec:** `docs/specs/MENTOR-LIVE-READINESS-SPEC.md` §Fix 2a "Sender side" + anti-loop #1 +
+round-2 adversarial F5 (token-leak scrub). PR 2 of the staged build, part b.
+**Change:** Extend `src/messaging/AgentTelegramComms.ts` with `sendAgentMessage` (the
+adapter-agnostic send function), a `SendAuditRow` schema + appender hook, and `scrubToken`
+(redacts the bot token from any error surface before it leaves the module). I/O still
+**injected** — fully unit-testable; no caller invokes it yet (dark). PR 3 wires it.
+**Files:** `src/messaging/AgentTelegramComms.ts` (additive), `tests/unit/messaging/AgentTelegramComms.test.ts` (+5).
+
+## What changed
+
+- `sendAgentMessage(input, deps)` — mints/uses `a2aId` (UUID-or-supplied), defaults
+  `correlationId` to `id` (prompts self-correlate; replies thread on the prompt's id),
+  formats the marker via `formatMarker`, calls the injected `deps.send(topicId, text)`,
+  and writes ONE audit row (always — on `ok`, `failed`, or `role-refused`). Returns
+  `{ok, a2aId, sentMessageId?, reason?}`.
+- **Runtime anti-loop guard** (spec §Fix 2a anti-loop #1): refuses any `role` not in
+  `deps.allowedRoles` — NO send attempted, NO marker formed, audit row with
+  `result: 'role-refused'`. This makes the import-surface lint (deferred to PR 3) a
+  backup rather than the only defense; the runtime guard always applies.
+- `scrubToken(s, token)` — redacts the bot token (full + secret-portion) from any
+  string before it leaves the module. Wired into every error/audit path in
+  `sendAgentMessage` (round-2 adversarial F5: Telegram 401 response bodies sometimes
+  echo the token).
+
+## The seven questions
+
+1. **Over-block.** The runtime role-refusal is exact — a caller that legitimately needs
+   role X passes it in `allowedRoles`. No false-positive refusal.
+2. **Under-block.** Every send path writes an audit row (ok / failed / role-refused) — no
+   silent drop. Token scrub runs on every reason-string surface (format errors, send
+   errors). The audit row schema explicitly forbids secrets (verified in the artifact).
+3. **Level-of-abstraction fit.** I/O injected (`send`, `appendAudit`, `now`, `mintId`,
+   `botToken`, `fromBotId`, `toBotId`). The function is the wire-level send/marker/audit
+   logic; storage choice (JSONL vs SQLite) is the caller's (PR 3 picks).
+4. **Signal vs authority.** Send is the authority on "did the message leave my process";
+   the result is exact (`ok` only when the adapter returns a messageId). Audit row is the
+   signal trail. No silent best-effort.
+5. **Interactions — dark, but the module surface is shared with PR 1 + the existing
+   `decideRoute`.** The send side adds NEW exports (sendAgentMessage, scrubToken,
+   SendAuditRow, etc.) — existing imports unaffected. Dark today.
+6. **External surfaces.** None new in this PR. The audit row schema is the wire format
+   for future log readers (Stage-B forensics will read it in PR 3).
+7. **Rollback cost.** Trivial — revert removes additive exports + tests. No data, no
+   migration. PR 1 / PR 2a are not touched.
+
+## Testing
+
+- 5 new unit tests (25 total in the file, all green):
+  - **send + audit happy path**: marker round-trips through `parseMarker` (the sender's
+    output is the receiver's input — closes the wire-format integration informally);
+    `result: 'ok'` audit row with `sentMessageId` + correct fields.
+  - **correlation threading**: explicit `correlationId` lands in the marker's `corr=`
+    and in the audit row (prompt↔reply linkage via Telegram chat history alone, per
+    Codey's round-2 design point).
+  - **ANTI-LOOP runtime refusal**: a role not in `allowedRoles` → no send, role-refused
+    audit row with explanatory reason. Proves the import-lint isn't the only defense.
+  - **send-error with token in body**: adapter throws an error containing the bot token
+    → result + audit reason both scrubbed (no token leak through any surface).
+  - **scrubToken unit**: full-token + secret-portion + no-token-present + undefined-token
+    coverage.
+- `tsc --noEmit` clean.
+
+## Migration parity
+
+None — additive exports to a dark module. No config, no routes, no agent-installed file
+changes. PR 3 wires the receiver-handler at `server.ts`, the role handlers, the audit
+ledger persistence (JSONL append via SafeFsExecutor), and the processed-id store (SQLite
+per the convention note flagged in PR 1's artifact); migration (file-outbox retirement,
+dead-config removal) lands there per the spec's §Migration parity.

package/upgrades/side-effects/telegram-adapter-multi-instance.md

@@ -0,0 +1,61 @@
+# Side-Effects Review — TelegramAdapter multi-instance isolation + Message-type extension (PR 2a)
+
+**Spec:** `docs/specs/MENTOR-LIVE-READINESS-SPEC.md` §Fix 2b "Implementation surface" items
+1-2 + round-2 integration F1 (converged, approved). PR 2 of the staged build, part a.
+**Change:** Make `TelegramAdapter` safe to run as a second (non-primary) instance in one
+process, and expose the Telegram fields the a2a spoof-defense needs. **Ships dark** — no
+caller passes the new options yet; the new Message fields are additive-optional.
+**Files:** `src/messaging/TelegramAdapter.ts`, `tests/unit/telegram-adapter-multi-instance.test.ts` (new).
+
+## What changed
+
+1. **Constructor opts `{ subDir?, suppressLifelineAutoCreate? }`** (3rd param, optional). When
+   `subDir` is set, the four per-bot state files (registry / message-log / poll-offset /
+   attention) live under `{stateDir}/{subDir}/` via a new `botStateDir`. The PRIMARY bot
+   (no `subDir`) gets `botStateDir === stateDir` → **paths are byte-for-byte unchanged**.
+2. **`suppressLifelineAutoCreate`** — `start()` skips `ensureLifelineTopic()` when true, so a
+   non-primary bot can't create a second Lifeline topic in the chat.
+3. **Message-type extension** — `message.from.is_bot?: boolean` + `message.sender_chat?` added
+   to `TelegramUpdate`. These are the structural inputs to the a2a user-spoof defense (a
+   human typing an `[a2a:…]` marker has `is_bot:false` and no `sender_chat`).
+
+## The seven questions
+
+1. **Over-block.** N/A — no gate. The only behavior gate is `suppressLifelineAutoCreate`,
+   default false (primary unaffected).
+2. **Under-block.** The reviewer-flagged collision (two adapters sharing
+   `telegram-poll-offset.json` → `poll()`'s cross-token detection fires continuously) is
+   eliminated: non-primary state is namespaced. Test asserts the two adapters share NO
+   state-file path.
+3. **Level-of-abstraction fit.** The isolation is at construction (one place), not scattered
+   per-callsite. `botStateDir` is the single source for per-bot paths.
+4. **Signal vs authority.** N/A.
+5. **Interactions — THE risk, and how it's bounded.** This file runs Echo's own (primary)
+   Telegram — the channel to the user. The change is built so the primary path is
+   **identical** (when `subDir` is undefined, `botStateDir === stateDir`). A dedicated test
+   asserts the four primary paths are byte-for-byte the historical `{stateDir}/...` values,
+   and the existing TelegramAdapter suites (71 tests across 5 files) pass unchanged — the
+   regression guard for "did I break my own comms." The new code only branches when `subDir`
+   is set, and nothing sets it yet (dark). Media/dashboard dirs still resolve off `stateDir`
+   inline — NOT isolated — which is fine: the reviewer flagged only the four constructor
+   state files, and the mentor bot (the only future `subDir` user) does no media/dashboard.
+6. **External surfaces.** None. No routes, no config consumed yet. The Message-type fields
+   are additive-optional (every existing reader ignores them).
+7. **Rollback cost.** Trivial — revert restores the 2-param constructor; no data, no migration
+   (the primary never wrote to a subDir).
+
+## Testing
+
+- `tests/unit/telegram-adapter-multi-instance.test.ts` (3 tests): **primary paths byte-for-byte
+  unchanged** (the load-bearing safety assertion); subDir namespaces all four state files +
+  shares no path with primary + creates the sub-dir; `suppressLifelineAutoCreate` recorded
+  (false default for primary).
+- Regression: existing Telegram suites (`TelegramAdapter`, `telegram-format-wireup`,
+  `telegram-adapter`) + the PR-1 `AgentTelegramComms` suite — 71 tests, all green.
+- `tsc --noEmit` clean.
+
+## Migration parity
+
+None — additive constructor option + additive optional Message fields. No agent-installed
+file change, no config consumed yet. PR 2b wires `sendAgentMessage` + the recipient handler;
+PR 3's config/migration is per the spec's §Migration parity.