instar 1.3.28 → 1.3.29

package/dist/messaging/AgentTelegramComms.d.ts

@@ -0,0 +1,156 @@
+/**
+ * AgentTelegramComms — agent-to-agent Telegram comms primitive.
+ *
+ * Spec: docs/specs/MENTOR-LIVE-READINESS-SPEC.md §Fix 2a (approved 2026-05-27).
+ *
+ * A robust, recipient-knows-it's-from-an-agent channel any agent can use to message
+ * another agent's bot over Telegram, with the indicator AND the anti-loop machinery as
+ * first-class infra. Justin's framing: "robust infra that indicates the message is from
+ * another agent… leverage infra to prevent the ping pong trap." The mentor is its first
+ * consumer (see MentorOnboarding*), but nothing here is mentor-specific.
+ *
+ * Every message carries a VISIBLE marker prefix in the body so (a) humans can audit at a
+ * glance and (b) the Telegram chat history alone reconstructs a round-trip when ledgers
+ * are unavailable:
+ *
+ *   [a2a:from=<sender> to=<recipient> role=<role> id=<id> corr=<corr> ts=<unix-ms> v=1]
+ *
+ *   <body>
+ *
+ * This file is the PURE logic (marker parse/format + routing decision + cycle-detection
+ * key). I/O (the actual Telegram send + the audit ledgers + the processed-id store) is
+ * injected so every branch is unit-testable. See §Fix 2a for the routing matrix and the
+ * anti-loop invariants this enforces.
+ */
+/** Current marker schema version. Bumps are explicit (reader-first rule — see spec). */
+export declare const A2A_VERSION = 1;
+export interface A2aMarker {
+    from: string;
+    to: string;
+    role: string;
+    id: string;
+    corr: string;
+    ts: number;
+    v: number;
+}
+export interface A2aMessage extends A2aMarker {
+    body: string;
+}
+export interface A2aSendFields {
+    from: string;
+    to: string;
+    role: string;
+    /** Stable id; minted by the caller/sender if absent. */
+    id: string;
+    /** Correlation id. Prompts self-correlate (corr === id); replies carry the prompt's id. */
+    corr: string;
+    ts: number;
+}
+/**
+ * Result of parsing an inbound Telegram message body for an a2a marker.
+ * - `no-marker`: not an agent message → caller falls through to normal user handling.
+ * - `malformed`: marker-shaped but invalid → caller DROPS (security event), never falls
+ *   through to user handling (spoof / broken-sender defense).
+ */
+export type ParseResult = {
+    ok: true;
+    msg: A2aMessage;
+} | {
+    ok: false;
+    kind: 'no-marker';
+} | {
+    ok: false;
+    kind: 'malformed';
+    detail: string;
+};
+/** Format a marker + body for sending. The inverse of {@link parseMarker}. */
+export declare function formatMarker(fields: A2aSendFields, body: string): string;
+/** Parse an inbound message body. Strict — see {@link ParseResult}. */
+export declare function parseMarker(raw: string): ParseResult;
+/** Per-recipient routing configuration (spec §Fix 2a recipient + anti-loop). */
+export interface RecipientConfig {
+    /** This agent's own name (the `to` an inbound message must target). */
+    localAgent: string;
+    /** Known agents → their Telegram bot identity. Only senders here are trusted. */
+    knownAgents: Record<string, {
+        botId: string;
+    }>;
+    /**
+     * Per-source role acceptance (round-2 adversarial F6): `{ fromAgent: allowedRoles[] }`.
+     * A compromised/buggy known agent sending an unexpected role is dropped, even if that
+     * role is accepted from a DIFFERENT source. Scoped admission.
+     */
+    acceptRoles: Record<string, string[]>;
+    /** Replay window: reject markers whose ts is outside ±this from now. Default 24h. */
+    skewWindowMs: number;
+    /** Highest marker version this recipient understands. Newer → dead-letter, not crash. */
+    maxVersion: number;
+}
+/**
+ * Inbound message context the caller resolves from the Telegram update. The bot-identity
+ * fields are the SPOOF DEFENSE: a human user typing a marker-shaped string has
+ * `senderIsBot === false` and no `senderChatId` → dropped (round-2 adversarial F1).
+ */
+export interface IncomingContext {
+    /** The raw message body (marker + body, or arbitrary user text). */
+    raw: string;
+    /** `from.is_bot` from the Telegram update. */
+    senderIsBot: boolean;
+    /** `sender_chat.id` from the Telegram update when present (group bot-as-channel relay).
+     *  Its mere presence is part of the spoof defense (a human user has none). */
+    senderChatId?: string;
+    /** The effective sender bot identity = `sender_chat.id ?? from.id`. Matched against the
+     *  allowlist's `botId`. The caller resolves this from the Telegram update. */
+    senderBotId?: string;
+    /** Wall-clock now (ms) — injected for testability. */
+    now: number;
+}
+export type RouteDropReason = 'agent-marker-malformed' | 'agent-marker-stale-or-future' | 'agent-marker-spoofed-by-user' | 'agent-marker-wrong-recipient' | 'agent-marker-unsupported-version' | 'agent-marker-unknown' | 'agent-marker-duplicate' | 'agent-marker-role-not-allowed-from-source' | 'agent-marker-unexpected-role' | 'agent-marker-unknown-role';
+export type RouteDecision = {
+    action: 'fall-through';
+} | {
+    action: 'route';
+    msg: A2aMessage;
+} | {
+    action: 'drop';
+    reason: RouteDropReason;
+    detail?: string;
+    msg?: A2aMessage;
+};
+/**
+ * The recipient routing matrix (spec §Fix 2a "Routing matrix"). PURE — every branch is a
+ * decision the caller then acts on (route to a role-handler, or drop + write an audit
+ * row). `knownRole` tells whether the role is one this recipient has a handler for at all;
+ * `isProcessed` is the idempotency check against the processed-id store.
+ */
+export declare function decideRoute(ctx: IncomingContext, cfg: RecipientConfig, deps: {
+    isProcessed: (id: string) => boolean;
+    knownRole: (role: string) => boolean;
+}): RouteDecision;
+/**
+ * Cycle-detection key (spec §Fix 2a anti-loop #3): keyed on the full tuple so legitimate
+ * unrelated traffic never collides. `corr` is always present (required in the marker), so
+ * the key cannot collapse to `undefined`.
+ */
+export declare function cycleKey(fields: {
+    fromBotId: string;
+    toBotId: string;
+    topicId: number | string;
+    role: string;
+    corr: string;
+}): string;
+/**
+ * In-memory cycle detector. A send is refused (unless `cycleOk`) when the same key was
+ * seen within `windowMs` — the structural guard against tight role↔reply ping-pong.
+ */
+export declare class CycleDetector {
+    private readonly windowMs;
+    private readonly recent;
+    constructor(windowMs: number);
+    /** Returns true if sending this key now would trip cycle-detection. */
+    wouldTrip(key: string, now: number): boolean;
+    /** Record a send/receive of this key at `now`. */
+    mark(key: string, now: number): void;
+    private evict;
+}
+//# sourceMappingURL=AgentTelegramComms.d.ts.map

package/dist/messaging/AgentTelegramComms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentTelegramComms.d.ts","sourceRoot":"","sources":["../../src/messaging/AgentTelegramComms.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,wFAAwF;AACxF,eAAO,MAAM,WAAW,IAAI,CAAC;AAuB7B,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,CAAC,EAAE,MAAM,CAAC;CACX;AAED,MAAM,WAAW,UAAW,SAAQ,SAAS;IAC3C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,EAAE,EAAE,MAAM,CAAC;IACX,2FAA2F;IAC3F,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,UAAU,CAAA;CAAE,GAC7B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAChC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAErD,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAmBxE;AAED,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAkBpD;AAED,gFAAgF;AAChF,MAAM,WAAW,eAAe;IAC9B,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACtC,qFAAqF;IACrF,YAAY,EAAE,MAAM,CAAC;IACrB,yFAAyF;IACzF,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ,8CAA8C;IAC9C,WAAW,EAAE,OAAO,CAAC;IACrB;kFAC8E;IAC9E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;kFAC8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,MAAM,eAAe,GACvB,wBAAwB,GACxB,8BAA8B,GAC9B,8BAA8B,GAC9B,8BAA8B,GAC9B,kCAAkC,GAClC,sBAAsB,GACtB,wBAAwB,GACxB,2CAA2C,GAC3C,8BAA8B,GAC9B,2BAA2B,CAAC;AAEhC,MAAM,MAAM,aAAa,GACrB;IAAE,MAAM,EAAE,cAAc,CAAA;CAAE,GAC1B;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,UAAU,CAAA;CAAE,GACpC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,eAAe,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,UAAU,CAAA;CAAE,CAAC;AAEnF;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,eAAe,EACpB,IAAI,EAAE;IAAE,WAAW,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IAAC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAA;CAAE,GACnF,aAAa,CAoDf;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,MAAM,CAET;AAED;;;GAGG;AACH,qBAAa,aAAa;IAEZ,OAAO,CAAC,QAAQ,CAAC,QAAQ;IADrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;gBACvB,QAAQ,EAAE,MAAM;IAE7C,uEAAuE;IACvE,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;IAM5C,kDAAkD;IAClD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAKpC,OAAO,CAAC,KAAK;CAKd"}

package/dist/messaging/AgentTelegramComms.js

@@ -0,0 +1,170 @@
+/**
+ * AgentTelegramComms — agent-to-agent Telegram comms primitive.
+ *
+ * Spec: docs/specs/MENTOR-LIVE-READINESS-SPEC.md §Fix 2a (approved 2026-05-27).
+ *
+ * A robust, recipient-knows-it's-from-an-agent channel any agent can use to message
+ * another agent's bot over Telegram, with the indicator AND the anti-loop machinery as
+ * first-class infra. Justin's framing: "robust infra that indicates the message is from
+ * another agent… leverage infra to prevent the ping pong trap." The mentor is its first
+ * consumer (see MentorOnboarding*), but nothing here is mentor-specific.
+ *
+ * Every message carries a VISIBLE marker prefix in the body so (a) humans can audit at a
+ * glance and (b) the Telegram chat history alone reconstructs a round-trip when ledgers
+ * are unavailable:
+ *
+ *   [a2a:from=<sender> to=<recipient> role=<role> id=<id> corr=<corr> ts=<unix-ms> v=1]
+ *
+ *   <body>
+ *
+ * This file is the PURE logic (marker parse/format + routing decision + cycle-detection
+ * key). I/O (the actual Telegram send + the audit ledgers + the processed-id store) is
+ * injected so every branch is unit-testable. See §Fix 2a for the routing matrix and the
+ * anti-loop invariants this enforces.
+ */
+/** Current marker schema version. Bumps are explicit (reader-first rule — see spec). */
+export const A2A_VERSION = 1;
+/** Marker field-value charset (spec: deterministic parsing, avoids invisible/escaping
+ *  cases). Agent/role/id/corr match this; ts and v are positive integers. */
+const TOKEN = '[A-Za-z0-9._:-]+';
+/**
+ * Strict marker regex — anchored to the start, consumes exactly the first line plus the
+ * required blank-line separator, then captures the body. Field ORDER is fixed (so the
+ * parse is deterministic and a reordered/extra-field marker is "malformed", not silently
+ * accepted). All of from/to/role/id/corr/ts/v are REQUIRED (corr + ts required per
+ * round-2/3 convergence — missing corr would collapse the cycle-detection key; missing ts
+ * disables replay-window defense).
+ */
+const MARKER_RE = new RegExp(`^\\[a2a:from=(${TOKEN}) to=(${TOKEN}) role=(${TOKEN}) id=(${TOKEN}) corr=(${TOKEN}) ts=([0-9]+) v=([0-9]+)\\]\\n\\n([\\s\\S]*)$`);
+/** A marker-shaped first line WITHOUT the strict full match — used only to distinguish
+ *  "not an agent message at all" (fall through to user handling) from "looks like one but
+ *  is malformed" (drop as a security event, NEVER fall through). */
+const MARKER_PREFIX_RE = /^\[a2a:/;
+/** Format a marker + body for sending. The inverse of {@link parseMarker}. */
+export function formatMarker(fields, body) {
+    for (const [k, v] of Object.entries({
+        from: fields.from,
+        to: fields.to,
+        role: fields.role,
+        id: fields.id,
+        corr: fields.corr,
+    })) {
+        if (!new RegExp(`^${TOKEN}$`).test(String(v))) {
+            throw new Error(`AgentTelegramComms.formatMarker: field "${k}" value "${v}" violates the a2a charset ${TOKEN}`);
+        }
+    }
+    if (!Number.isInteger(fields.ts) || fields.ts <= 0) {
+        throw new Error(`AgentTelegramComms.formatMarker: ts must be a positive integer, got ${fields.ts}`);
+    }
+    return (`[a2a:from=${fields.from} to=${fields.to} role=${fields.role} id=${fields.id} ` +
+        `corr=${fields.corr} ts=${fields.ts} v=${A2A_VERSION}]\n\n${body}`);
+}
+/** Parse an inbound message body. Strict — see {@link ParseResult}. */
+export function parseMarker(raw) {
+    if (typeof raw !== 'string' || !MARKER_PREFIX_RE.test(raw)) {
+        return { ok: false, kind: 'no-marker' };
+    }
+    const m = MARKER_RE.exec(raw);
+    if (!m) {
+        return { ok: false, kind: 'malformed', detail: 'marker prefix present but failed strict parse' };
+    }
+    const [, from, to, role, id, corr, tsStr, vStr, body] = m;
+    const ts = Number(tsStr);
+    const v = Number(vStr);
+    if (!Number.isInteger(ts) || ts <= 0) {
+        return { ok: false, kind: 'malformed', detail: `invalid ts "${tsStr}"` };
+    }
+    if (!Number.isInteger(v) || v <= 0) {
+        return { ok: false, kind: 'malformed', detail: `invalid v "${vStr}"` };
+    }
+    return { ok: true, msg: { from, to, role, id, corr, ts, v, body } };
+}
+/**
+ * The recipient routing matrix (spec §Fix 2a "Routing matrix"). PURE — every branch is a
+ * decision the caller then acts on (route to a role-handler, or drop + write an audit
+ * row). `knownRole` tells whether the role is one this recipient has a handler for at all;
+ * `isProcessed` is the idempotency check against the processed-id store.
+ */
+export function decideRoute(ctx, cfg, deps) {
+    const parsed = parseMarker(ctx.raw);
+    if (!parsed.ok && parsed.kind === 'no-marker')
+        return { action: 'fall-through' };
+    if (!parsed.ok)
+        return { action: 'drop', reason: 'agent-marker-malformed', detail: parsed.detail };
+    const msg = parsed.msg;
+    // Replay / clock-skew window (round-2 adversarial F2).
+    if (Math.abs(ctx.now - msg.ts) > cfg.skewWindowMs) {
+        return { action: 'drop', reason: 'agent-marker-stale-or-future', msg };
+    }
+    // Unsupported version → dead-letter, never crash (reader-first rule).
+    if (msg.v > cfg.maxVersion) {
+        return { action: 'drop', reason: 'agent-marker-unsupported-version', msg };
+    }
+    // SPOOF DEFENSE (round-2 adversarial F1): a real user typing a marker-shaped string is
+    // not a bot and has no sender_chat. Drop before any allowlist/role check — a human-typed
+    // marker must NEVER reach a role-handler, even if from/id happen to match.
+    if (!ctx.senderIsBot && ctx.senderChatId === undefined) {
+        return { action: 'drop', reason: 'agent-marker-spoofed-by-user', msg };
+    }
+    // Recipient targeting.
+    if (msg.to !== cfg.localAgent) {
+        return { action: 'drop', reason: 'agent-marker-wrong-recipient', msg };
+    }
+    // Sender allowlist + bot-identity match.
+    const known = cfg.knownAgents[msg.from];
+    if (!known || (ctx.senderBotId !== undefined && known.botId !== ctx.senderBotId)) {
+        return { action: 'drop', reason: 'agent-marker-unknown', msg };
+    }
+    // Idempotency (round-2 adversarial: Telegram retry / adapter restart).
+    if (deps.isProcessed(msg.id)) {
+        return { action: 'drop', reason: 'agent-marker-duplicate', msg };
+    }
+    // Per-source role acceptance (round-2 adversarial F6): scoped admission.
+    const allowedFromSource = cfg.acceptRoles[msg.from] ?? [];
+    if (!allowedFromSource.includes(msg.role)) {
+        // Distinguish "this recipient has no handler for the role at all" from "the role
+        // exists but isn't allowed from THIS source" — both drop, different audit codes.
+        if (!deps.knownRole(msg.role)) {
+            return { action: 'drop', reason: 'agent-marker-unknown-role', msg };
+        }
+        return { action: 'drop', reason: 'agent-marker-role-not-allowed-from-source', msg };
+    }
+    return { action: 'route', msg };
+}
+/**
+ * Cycle-detection key (spec §Fix 2a anti-loop #3): keyed on the full tuple so legitimate
+ * unrelated traffic never collides. `corr` is always present (required in the marker), so
+ * the key cannot collapse to `undefined`.
+ */
+export function cycleKey(fields) {
+    return `${fields.fromBotId}|${fields.toBotId}|${fields.topicId}|${fields.role}|${fields.corr}`;
+}
+/**
+ * In-memory cycle detector. A send is refused (unless `cycleOk`) when the same key was
+ * seen within `windowMs` — the structural guard against tight role↔reply ping-pong.
+ */
+export class CycleDetector {
+    windowMs;
+    recent = new Map();
+    constructor(windowMs) {
+        this.windowMs = windowMs;
+    }
+    /** Returns true if sending this key now would trip cycle-detection. */
+    wouldTrip(key, now) {
+        this.evict(now);
+        const last = this.recent.get(key);
+        return last !== undefined && now - last < this.windowMs;
+    }
+    /** Record a send/receive of this key at `now`. */
+    mark(key, now) {
+        this.recent.set(key, now);
+        this.evict(now);
+    }
+    evict(now) {
+        for (const [k, t] of this.recent) {
+            if (now - t >= this.windowMs)
+                this.recent.delete(k);
+        }
+    }
+}
+//# sourceMappingURL=AgentTelegramComms.js.map

package/dist/messaging/AgentTelegramComms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentTelegramComms.js","sourceRoot":"","sources":["../../src/messaging/AgentTelegramComms.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.28",
+  "version": "1.3.29",
   "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-27T21:23:16.473Z",
-  "instarVersion": "1.3.28",
+  "generatedAt": "2026-05-27T21:27:57.206Z",
+  "instarVersion": "1.3.29",
   "entryCount": 192,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.29.md

@@ -0,0 +1,42 @@
+# Instar Upgrade Guide — NEXT
+
+<!-- bump: minor -->
+
+## What Changed
+
+**New building block: agent-to-agent Telegram comms primitive (core logic).** This is the
+first piece of a robust, reusable way for two Instar agents to talk over Telegram *knowingly*
+— every agent-to-agent message carries a visible marker
+(`[a2a:from=… to=… role=… id=… corr=… ts=… v=1]`) so the receiving side can tell it's from
+another agent and apply anti-loop machinery, rather than treating it like a human user
+message. This increment ships the pure, security-critical core: the strict marker
+parser/formatter, the recipient routing decision (with the full drop matrix — malformed,
+replay-window, user-spoof, wrong-recipient, unknown-sender, duplicate, and per-source role
+admission), and the cycle-detection key. It ships **dark** — nothing wires it yet (the
+TelegramAdapter integration and the first consumer, the mentor, land in follow-up PRs).
+
+## What to Tell Your User
+
+- Nothing changes in how your agent behaves today — this is groundwork. It's the foundation
+  for agents being able to message each other over Telegram safely (with built-in defenses
+  so they can't spoof each other or get stuck in a reply loop), which a later update will
+  switch on for the mentor feature.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| `AgentTelegramComms` primitive (core) | Internal `parseMarker` / `formatMarker` / `decideRoute` / `CycleDetector` in `src/messaging/AgentTelegramComms.ts` — pure logic, I/O injected; not wired yet |
+
+## Evidence
+
+**Net-new feature, not a bug fix** — a new pure-logic module that nothing imports yet
+(ships dark). Proven by 20 unit tests covering every branch of the security-critical logic:
+marker parse/format (valid; no-marker vs malformed incl. missing `corr`/`ts`, charset
+violation, no separator; round-trip); the full routing matrix (route + fall-through + every
+drop reason, including the **user-spoof defense** — a human typing a marker-shaped string is
+dropped even when from/id match an allowlisted bot — and **per-source role acceptance** — a
+known role from the wrong source is dropped); and cycle-detection (key never collapses,
+trips within window, no false collision). `tsc --noEmit` clean. The integration + e2e tiers
+(real TelegramAdapter wiring, the bidirectional contract test, the supervised live cycle)
+land with the follow-up PRs per the spec's staged plan.

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

@@ -0,0 +1,75 @@
+# Side-Effects Review — Agent-to-Agent Telegram comms primitive (core logic, PR 1)
+
+**Spec:** `docs/specs/MENTOR-LIVE-READINESS-SPEC.md` §Fix 2a (converged, approved by Justin
+2026-05-27). Convergence report: `docs/specs/reports/mentor-live-readiness-convergence.md`.
+**Change:** New module `src/messaging/AgentTelegramComms.ts` — the PURE, security-critical
+core of the agent-to-agent Telegram comms primitive: strict marker parse/format, the
+recipient routing matrix (every drop branch), and cycle-detection. I/O (the actual Telegram
+send, audit ledgers, processed-id store) is **injected**, so this PR is pure logic + tests;
+the TelegramAdapter wiring + ledger persistence is PR 2, the mentor consumer is PR 3.
+**Files:** `src/messaging/AgentTelegramComms.ts` (new), `tests/unit/messaging/AgentTelegramComms.test.ts` (new).
+**Ships dark:** nothing imports the module yet except its test — zero runtime behavior change.
+
+## Principle check (Phase 1)
+
+Decision point? Yes — this is the recipient admission/routing decision (`decideRoute`) and
+the anti-loop cycle key. It is built as PURE functions returning a decision the caller acts
+on; the blocking authority (drop vs route) is explicit + exhaustively tested. No existing
+gate is loosened (nothing wired yet).
+
+## The seven questions
+
+1. **Over-block.** `decideRoute` drops on every ambiguous/unrecognized shape (malformed,
+   stale, spoofed, wrong-recipient, unknown-version, unknown-sender, duplicate,
+   role-not-allowed). Correct posture for a security boundary — a marker-shaped string is
+   guilty until allowlisted. The only fall-through is a genuine no-marker (normal user msg).
+2. **Under-block.** The spoof defense (`!senderIsBot && senderChatId===undefined` → drop)
+   is the round-2 adversarial F1 closure — a human typing a marker can NEVER reach a
+   role-handler, even if from/id match. Tested explicitly. `corr`/`ts` are required in the
+   parser so neither the cycle key nor the replay window can be bypassed by omission.
+3. **Level-of-abstraction fit.** Pure logic separated from I/O — the security decisions are
+   unit-testable in isolation (20 tests, every branch). I/O injection deferred to PR 2.
+4. **Signal vs authority.** `decideRoute` IS the authority (drop/route); it returns a typed
+   decision + audit reason for every branch (no silent drops — caller writes the audit row).
+5. **Interactions.** Module is dark (imported only by its test). No interaction with the
+   running system yet. PR 2 wires it into TelegramAdapter (multi-instance + handler-chain);
+   PR 3 wires the mentor consumer. Each subsequent PR re-runs the gate against the same spec.
+6. **External surfaces.** None in this PR (no routes, no config consumed yet). The marker
+   format is the wire contract for PR 2/3 + Codey's side; `A2A_VERSION` is exported for
+   version pinning.
+7. **Rollback cost.** Trivial — revert removes an unused module. No data, no migration.
+
+## Build-time refinements beyond the spec text
+
+- The spec mentioned `state/a2a-*.jsonl` (append-only JSONL audit) + a processed-id JSON
+  store. Convention note (MessageProcessingLedger header: "NOT a new ad-hoc JSON file") —
+  PR 2 will implement the processed-id store on the SQLite path (matching
+  PendingRelayStore/CommitmentTracker) rather than a JSON file; the append-only audit
+  ledgers stay JSONL (Codey designed the audit-row schema as JSONL, and append-only JSONL
+  is the right shape for a forensic trail). Flagged here so PR 2's choice is intentional.
+- `senderBotId` resolution (`sender_chat.id ?? from.id`) + `senderIsBot` are passed in by
+  the caller (PR 2 resolves them from the Telegram update, after the Message type is
+  extended to expose `is_bot`/`sender_chat`). The pure core only consumes them.
+
+## Testing
+
+- 20 unit tests (`tests/unit/messaging/AgentTelegramComms.test.ts`), all passing:
+  - **Marker parse/format**: valid parse; no-marker (fall-through) vs malformed (drop) —
+    incl. missing `corr`, missing `ts`, charset violation, no blank-line separator;
+    format↔parse round-trip; format rejects charset-violating fields.
+  - **Routing matrix**: route success; fall-through; and every drop branch — malformed,
+    stale/future (replay), **user-spoof** (human-typed marker dropped even when from/id
+    match), group bot-as-channel accept, wrong-recipient, unsupported-version, unknown
+    sender, bot-id mismatch, duplicate, **role-not-allowed-from-source** (notify from echo
+    dropped even though notify is a known role), unknown-role.
+  - **Cycle-detection**: key never collapses (corr always present); trips within window,
+    clears after; no collision on different corr.
+- tsc --noEmit clean.
+- PR 2/3 add the integration + e2e tiers (TelegramAdapter wiring, mentor consumer, the
+  bidirectional contract test, the supervised live cycle).
+
+## Migration parity
+
+None for this PR — a new unwired module. No agent-installed file changes, no config, no
+routes. PR 2/3 carry the config defaults + migration (file-outbox retirement, dead-config
+removal) per the spec's §Migration parity.