instar 1.3.36 → 1.3.37

package/dist/messaging/AgentTelegramLedger.d.ts

@@ -0,0 +1,65 @@
+/**
+ * AgentTelegramLedger — append-only audit trail for the agent-to-agent Telegram comms
+ * primitive (spec MENTOR-LIVE-READINESS §Fix 2a "Round-trip audit ledger" + Codey's
+ * round-2 design point: separate sent + received JSONLs so Stage-B forensics can
+ * reconstruct the round trip from the ledger files alone, OR from Telegram chat history
+ * alone via the visible `corr=` field).
+ *
+ * Conventions:
+ * - Append-only JSONL (atomic at line granularity on POSIX for `<PIPE_BUF` writes —
+ *   the same rationale the original mentor-outbox used; documented so a future reviewer
+ *   doesn't "fix" it to atomicWriteFileSync, which is wrong for append).
+ * - **No secrets in any row** (round-2 adversarial F5 — and the SendAuditRow shape
+ *   explicitly excludes the bot token; the ReceiveAuditRow only captures routing-level
+ *   marker fields, never the body).
+ * - Default paths: `{stateDir}/a2a-sent.jsonl` + `{stateDir}/a2a-received.jsonl`. The
+ *   caller may override (per-agent isolation, tests).
+ *
+ * I/O is the only side-effect; everything else is pure data.
+ */
+import type { SendAuditRow, RouteDropReason } from './AgentTelegramComms.js';
+/** Audit row written by the recipient wiring on every a2a event that was either routed
+ *  to a role-handler or dropped. NO row is written when the message is `no-marker`
+ *  (fall-through to normal user handling) — that would log every user message. */
+export interface ReceiveAuditRow {
+    localTs: string;
+    direction: 'received';
+    decision: 'routed' | 'dropped';
+    /** When `dropped`, the reason code from the routing matrix (see RouteDropReason). */
+    dropReason?: RouteDropReason | 'agent-marker-malformed';
+    /** Parsed marker fields — present when the parse succeeded, undefined for malformed. */
+    fromAgent?: string;
+    toAgent?: string;
+    role?: string;
+    id?: string;
+    corr?: string;
+    ts?: number;
+    /** Telegram-side identifiers, when resolved. */
+    telegramFromBotId?: string;
+    telegramSenderChatId?: string;
+    topicId?: number;
+    /** First 200 chars of the raw inbound (post-marker-strip on route; raw on drop) so
+     *  forensic readers can reconstruct what happened from the ledger alone. NEVER the
+     *  full body for routed rows — the body went to the role-handler. */
+    rawPrefix?: string;
+}
+export interface AgentTelegramLedgerPaths {
+    sentPath: string;
+    receivedPath: string;
+}
+export declare function defaultLedgerPaths(stateDir: string): AgentTelegramLedgerPaths;
+/**
+ * Append-only JSONL audit ledger. Both `appendSent` and `appendReceived` are synchronous
+ * + best-effort: they NEVER throw (an audit-write failure must not crash a tick). Writes
+ * use `fs.appendFileSync` because atomic-write-replace is wrong for append-only files
+ * (see the documented rationale in the module header).
+ */
+export declare class AgentTelegramLedger {
+    private readonly sentPath;
+    private readonly receivedPath;
+    constructor(paths: AgentTelegramLedgerPaths);
+    appendSent(row: SendAuditRow): void;
+    appendReceived(row: ReceiveAuditRow): void;
+    private appendLine;
+}
+//# sourceMappingURL=AgentTelegramLedger.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AgentTelegramLedger.d.ts","sourceRoot":"","sources":["../../src/messaging/AgentTelegramLedger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE7E;;kFAEkF;AAClF,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,UAAU,CAAC;IACtB,QAAQ,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC/B,qFAAqF;IACrF,UAAU,CAAC,EAAE,eAAe,GAAG,wBAAwB,CAAC;IACxD,wFAAwF;IACxF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,gDAAgD;IAChD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;yEAEqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,wBAAwB,CAK7E;AAED;;;;;GAKG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAE1B,KAAK,EAAE,wBAAwB;IAK3C,UAAU,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI;IAInC,cAAc,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI;IAI1C,OAAO,CAAC,UAAU;CAYnB"}

package/dist/messaging/AgentTelegramLedger.js

@@ -0,0 +1,61 @@
+/**
+ * AgentTelegramLedger — append-only audit trail for the agent-to-agent Telegram comms
+ * primitive (spec MENTOR-LIVE-READINESS §Fix 2a "Round-trip audit ledger" + Codey's
+ * round-2 design point: separate sent + received JSONLs so Stage-B forensics can
+ * reconstruct the round trip from the ledger files alone, OR from Telegram chat history
+ * alone via the visible `corr=` field).
+ *
+ * Conventions:
+ * - Append-only JSONL (atomic at line granularity on POSIX for `<PIPE_BUF` writes —
+ *   the same rationale the original mentor-outbox used; documented so a future reviewer
+ *   doesn't "fix" it to atomicWriteFileSync, which is wrong for append).
+ * - **No secrets in any row** (round-2 adversarial F5 — and the SendAuditRow shape
+ *   explicitly excludes the bot token; the ReceiveAuditRow only captures routing-level
+ *   marker fields, never the body).
+ * - Default paths: `{stateDir}/a2a-sent.jsonl` + `{stateDir}/a2a-received.jsonl`. The
+ *   caller may override (per-agent isolation, tests).
+ *
+ * I/O is the only side-effect; everything else is pure data.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+export function defaultLedgerPaths(stateDir) {
+    return {
+        sentPath: path.join(stateDir, 'a2a-sent.jsonl'),
+        receivedPath: path.join(stateDir, 'a2a-received.jsonl'),
+    };
+}
+/**
+ * Append-only JSONL audit ledger. Both `appendSent` and `appendReceived` are synchronous
+ * + best-effort: they NEVER throw (an audit-write failure must not crash a tick). Writes
+ * use `fs.appendFileSync` because atomic-write-replace is wrong for append-only files
+ * (see the documented rationale in the module header).
+ */
+export class AgentTelegramLedger {
+    sentPath;
+    receivedPath;
+    constructor(paths) {
+        this.sentPath = paths.sentPath;
+        this.receivedPath = paths.receivedPath;
+    }
+    appendSent(row) {
+        this.appendLine(this.sentPath, row);
+    }
+    appendReceived(row) {
+        this.appendLine(this.receivedPath, row);
+    }
+    appendLine(target, row) {
+        try {
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            fs.appendFileSync(target, JSON.stringify(row) + '\n', 'utf-8');
+        }
+        catch (err) {
+            // Best-effort audit: an audit-write failure must not crash a tick. Log but swallow.
+            // (Spec §Fix 2a "every drop path writes an audit row" — silent drops make Stage-B
+            // forensics painful, but a CRASHED tick is worse. We accept this trade-off.)
+            // eslint-disable-next-line no-console
+            console.warn(`[a2a-ledger] append failed (non-fatal) at ${target}:`, err instanceof Error ? err.message : String(err));
+        }
+    }
+}
+//# sourceMappingURL=AgentTelegramLedger.js.map

package/dist/messaging/AgentTelegramLedger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentTelegramLedger.js","sourceRoot":"","sources":["../../src/messaging/AgentTelegramLedger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAkC7B,MAAM,UAAU,kBAAkB,CAAC,QAAgB;IACjD,OAAO;QACL,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,gBAAgB,CAAC;QAC/C,YAAY,EAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,oBAAoB,CAAC;KACxD,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,OAAO,mBAAmB;IACb,QAAQ,CAAS;IACjB,YAAY,CAAS;IAEtC,YAAY,KAA+B;QACzC,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;QAC/B,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC;IACzC,CAAC;IAED,UAAU,CAAC,GAAiB;QAC1B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACtC,CAAC;IAED,cAAc,CAAC,GAAoB;QACjC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC;IAC1C,CAAC;IAEO,UAAU,CAAC,MAAc,EAAE,GAAY;QAC7C,IAAI,CAAC;YACH,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACxD,EAAE,CAAC,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;QACjE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,oFAAoF;YACpF,kFAAkF;YAClF,6EAA6E;YAC7E,sCAAsC;YACtC,OAAO,CAAC,IAAI,CAAC,6CAA6C,MAAM,GAAG,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QACzH,CAAC;IACH,CAAC;CACF"}

package/dist/messaging/ProcessedIdStore.d.ts

@@ -0,0 +1,48 @@
+/**
+ * ProcessedIdStore — small persistent set of recently-processed a2a marker `id`s, so
+ * Telegram retries / adapter restarts can't double-inject the same prompt (spec
+ * MENTOR-LIVE-READINESS §Fix 2a "Processed-id ledger" + Codey's round-2 design point).
+ *
+ * Bounded by `maxEntries` (default 10_000) AND `maxAgeMs` (default 30 days) — whichever
+ * evicts first. **Bounded eviction is the same surface adversarial F2 worried about**:
+ * an `id` that ages out is no longer "duplicate" and could be re-injected by a replayer
+ * who captured it. The marker's `ts` + skew-window (24h default) is the defense at the
+ * primitive layer; this store's eviction policy is set generously so legitimate retries
+ * within hours/days are still de-duped.
+ *
+ * Convention note: instar prefers SQLite for durable dedup ledgers (MessageProcessingLedger,
+ * CommitmentTracker). This store uses a small JSON file because the working set is small
+ * (per-mentee processed-ids over 30d), the file is rewritten atomically on every mark, and
+ * there's no concurrent-writer story to need WAL. A future bump to SQLite is a drop-in
+ * replacement at the class boundary.
+ */
+export interface ProcessedIdStoreOptions {
+    /** Absolute path to the JSON file backing the store. */
+    filePath: string;
+    /** Max entries to retain before evicting the oldest (default 10_000). */
+    maxEntries?: number;
+    /** Max age (ms) before an entry is evicted (default 30 days). */
+    maxAgeMs?: number;
+    /** Injected for testability. Default: Date.now. */
+    now?: () => number;
+}
+export declare class ProcessedIdStore {
+    private readonly filePath;
+    private readonly maxEntries;
+    private readonly maxAgeMs;
+    private readonly now;
+    private entries;
+    constructor(opts: ProcessedIdStoreOptions);
+    /** True if the id has been marked + has not been evicted. */
+    hasProcessed(id: string): boolean;
+    /** Mark this id processed at now() and persist. Idempotent (re-marking is a no-op
+     *  beyond refreshing the persisted snapshot). */
+    markProcessed(id: string): void;
+    /** Test helper: current entry count. */
+    size(): number;
+    private load;
+    private persist;
+    private evictExpired;
+    private evictOverflow;
+}
+//# sourceMappingURL=ProcessedIdStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ProcessedIdStore.d.ts","sourceRoot":"","sources":["../../src/messaging/ProcessedIdStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,MAAM,WAAW,uBAAuB;IACtC,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAgBD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,OAAO,CAA+B;gBAElC,IAAI,EAAE,uBAAuB;IASzC,6DAA6D;IAC7D,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAKjC;qDACiD;IACjD,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAS/B,wCAAwC;IACxC,IAAI,IAAI,MAAM;IAKd,OAAO,CAAC,IAAI;IAmBZ,OAAO,CAAC,OAAO;IAef,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,aAAa;CAStB"}

package/dist/messaging/ProcessedIdStore.js

@@ -0,0 +1,111 @@
+/**
+ * ProcessedIdStore — small persistent set of recently-processed a2a marker `id`s, so
+ * Telegram retries / adapter restarts can't double-inject the same prompt (spec
+ * MENTOR-LIVE-READINESS §Fix 2a "Processed-id ledger" + Codey's round-2 design point).
+ *
+ * Bounded by `maxEntries` (default 10_000) AND `maxAgeMs` (default 30 days) — whichever
+ * evicts first. **Bounded eviction is the same surface adversarial F2 worried about**:
+ * an `id` that ages out is no longer "duplicate" and could be re-injected by a replayer
+ * who captured it. The marker's `ts` + skew-window (24h default) is the defense at the
+ * primitive layer; this store's eviction policy is set generously so legitimate retries
+ * within hours/days are still de-duped.
+ *
+ * Convention note: instar prefers SQLite for durable dedup ledgers (MessageProcessingLedger,
+ * CommitmentTracker). This store uses a small JSON file because the working set is small
+ * (per-mentee processed-ids over 30d), the file is rewritten atomically on every mark, and
+ * there's no concurrent-writer story to need WAL. A future bump to SQLite is a drop-in
+ * replacement at the class boundary.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { SafeFsExecutor } from '../core/SafeFsExecutor.js';
+const DEFAULT_MAX_ENTRIES = 10_000;
+const DEFAULT_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+export class ProcessedIdStore {
+    filePath;
+    maxEntries;
+    maxAgeMs;
+    now;
+    entries;
+    constructor(opts) {
+        this.filePath = opts.filePath;
+        this.maxEntries = opts.maxEntries ?? DEFAULT_MAX_ENTRIES;
+        this.maxAgeMs = opts.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
+        this.now = opts.now ?? Date.now;
+        this.entries = new Map();
+        this.load();
+    }
+    /** True if the id has been marked + has not been evicted. */
+    hasProcessed(id) {
+        this.evictExpired();
+        return this.entries.has(id);
+    }
+    /** Mark this id processed at now() and persist. Idempotent (re-marking is a no-op
+     *  beyond refreshing the persisted snapshot). */
+    markProcessed(id) {
+        if (!this.entries.has(id)) {
+            this.entries.set(id, { ts: this.now() });
+        }
+        this.evictExpired();
+        this.evictOverflow();
+        this.persist();
+    }
+    /** Test helper: current entry count. */
+    size() {
+        this.evictExpired();
+        return this.entries.size;
+    }
+    load() {
+        if (!fs.existsSync(this.filePath))
+            return;
+        try {
+            const raw = fs.readFileSync(this.filePath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            if (parsed && parsed.v === 1 && parsed.entries && typeof parsed.entries === 'object') {
+                for (const [id, ts] of Object.entries(parsed.entries)) {
+                    if (typeof ts === 'number' && Number.isFinite(ts)) {
+                        this.entries.set(id, { ts });
+                    }
+                }
+            }
+        }
+        catch {
+            // Corrupted store → start fresh (full re-allow). Better than crashing the recipient
+            // — duplicate prompts are recoverable; a dead recipient isn't.
+            this.entries = new Map();
+        }
+    }
+    persist() {
+        const file = {
+            v: 1,
+            entries: Object.fromEntries([...this.entries].map(([id, r]) => [id, r.ts])),
+        };
+        try {
+            fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+            SafeFsExecutor.atomicWriteJsonSync(this.filePath, file, { operation: 'ProcessedIdStore.persist' });
+        }
+        catch (err) {
+            // Best-effort persistence; on the next mark we retry.
+            // eslint-disable-next-line no-console
+            console.warn(`[a2a-processed-id] persist failed (non-fatal) at ${this.filePath}:`, err instanceof Error ? err.message : String(err));
+        }
+    }
+    evictExpired() {
+        const cutoff = this.now() - this.maxAgeMs;
+        for (const [id, r] of this.entries) {
+            if (r.ts < cutoff)
+                this.entries.delete(id);
+        }
+    }
+    evictOverflow() {
+        if (this.entries.size <= this.maxEntries)
+            return;
+        // Drop oldest first.
+        const sorted = [...this.entries].sort((a, b) => a[1].ts - b[1].ts);
+        const dropCount = this.entries.size - this.maxEntries;
+        for (let i = 0; i < dropCount; i++) {
+            this.entries.delete(sorted[i][0]);
+        }
+    }
+}
+//# sourceMappingURL=ProcessedIdStore.js.map

package/dist/messaging/ProcessedIdStore.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.36",
+  "version": "1.3.37",
   "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-27T23:50:57.603Z",
-  "instarVersion": "1.3.36",
+  "generatedAt": "2026-05-27T23:52:19.576Z",
+  "instarVersion": "1.3.37",
   "entryCount": 192,
   "entries": {
     "hook:session-start": {

package/upgrades/{1.3.36.md → 1.3.37.md}

@@ -15,11 +15,27 @@ The **Release-Readiness Visibility** spec (`docs/specs/RELEASE-READINESS-VISIBIL
 
 The fix path for an existing silent stall: the watchdog opens an Attention item; auto-draft fills NEXT.md but BOTH publish gates refuse it until a human reviews each section (replacing the marker with a hash-locked receipt); rollback flips a state-file kill-switch loudly.
 
+---
+
+**Agent-to-agent Telegram comms primitive — receiver-side storage primitives.** Two new
+internal modules the next update will use to wire the recipient side of the a2a primitive,
+both **dark** (no caller yet):
+
+- `AgentTelegramLedger` — append-only JSONL audit trail of every a2a send and every a2a
+  receive decision (routed or dropped, with the drop reason). Best-effort + non-throwing
+  (an audit-write failure must not crash a tick).
+- `ProcessedIdStore` — bounded persistent set of recently-processed marker `id`s, so
+  Telegram retries or adapter restarts can't double-inject the same prompt. Bounded by
+  `maxEntries` (10k default) AND `maxAgeMs` (30d default). Backed by an atomic-write JSON
+  file via SafeFsExecutor; corrupt-file recovery (starts fresh rather than crash the
+  recipient).
+
 ## What to Tell Your User
 
 - **I'll notice if my own ship is stuck**: when changes pile up and a release stops going out, I now raise a single, calm flag on my attention list — and the longer it sits, the louder that flag gets. You don't have to remember to check whether I'm actually shipping; I'll tell you when I'm not.
 - **The release notes draft themselves**: instead of waiting for someone to write release notes from scratch, the toolchain now sketches a starter version from the change list. A human still has to read and sign off on each section before it can publish — the safety net stays in place; it just isn't a blank page anymore.
 - **A merged feature can no longer be invisible to my own systems**: my feature board used to read whatever was on my laptop, which sometimes meant brand-new merged features didn't show up. It can now read the real shared copy directly, so the newest work stops being the most-hidden work.
+- The agent-to-agent Telegram comms infrastructure continues to land in pieces; still plumbing, nothing user-visible changes today.
 
 This change is off by default everywhere. I'll dogfood it on myself first.
 
@@ -31,9 +47,13 @@ This change is off by default everywhere. I'll dogfood it on myself first.
 | Auto-draft an upgrade guide | `node scripts/analyze-release.js --draft-guide` (writes `upgrades/NEXT.md` with unreviewed markers) |
 | Canonical-ref spec scan | Set `featureRollout.canonicalRefScan: true` and `featureRollout.canonicalRemote` in `.instar/config.json` |
 | Enable the watchdog | Set `monitoring.releaseReadiness.enabled: true` in `.instar/config.json`; the `release-readiness-check` job runs every 6h (still ships disabled — flip it on per agent) |
+| `AgentTelegramLedger` | Internal — `new AgentTelegramLedger(defaultLedgerPaths(stateDir))`; `appendSent(row)` + `appendReceived(row)`; JSONL, best-effort non-throwing |
+| `ProcessedIdStore` | Internal — `new ProcessedIdStore({filePath, maxEntries?, maxAgeMs?})`; `hasProcessed(id)` + `markProcessed(id)`; bounded + persistent |
 
 ## Evidence
 
 The Layer B real-I/O E2E (`tests/e2e/release-readiness-live.test.ts`) reproduces the original silent-stall shape against a fixture instar repo (real git fetch + real `analyze-release.js` subprocess + real `merge-base`) and asserts that exactly one Attention item is raised for an aged, blocked backlog. The Layer A unit tests (`tests/unit/analyze-release-draft-guide.test.ts` and `tests/unit/upgrade-guide-autodraft-review.test.ts`) reproduce the placeholder-text bypass adversarial review caught (the analyzer's `'Review the commit for specifics'` fallback that previously could pass the section-presence gate) and confirm the new validator blocks it. The Layer C unit test (`tests/unit/featureRolloutScan-canonical.test.ts`) reproduces the exact bug — a spec deleted from the local working tree but committed to main — and confirms the canonical scan still detects it as merged. ~64 tests added across three layered tiers, all green.
 
 Additionally, this very NEXT.md authoring revealed the meta-failure: the two PRs above merged but their publishes silently skipped because **NEXT.md didn't exist** — exactly the silent-skip mechanism Layer A + Layer B were built to surface. This guide is the unblock; once it publishes, the watchdog this guide describes goes live and can catch the same shape next time.
+
+Plus, the a2a comms storage primitives shipping here have 8 unit tests, all green: ledger writes to distinct files (append-only JSONL, one row per event); ledger captures the drop reason on routing-matrix drops; ledger never throws when the target is unwritable (best-effort guard tested by pointing at an unwritable path); store marks + recalls + persists across re-open; store evicts by `maxAgeMs` and by `maxEntries` (oldest first); store survives a corrupted file (starts fresh, doesn't crash); re-marking the same id is idempotent (first-seen-ts preserved).

package/upgrades/side-effects/a2a-ledger-and-processed-id-store.md

@@ -0,0 +1,68 @@
+# Side-Effects Review — a2a audit ledger + processed-id store (PR 3a)
+
+**Spec:** `docs/specs/MENTOR-LIVE-READINESS-SPEC.md` §Fix 2a "Round-trip audit ledger" +
+"Processed-id ledger" + Codey's round-2 idempotency-on-receive design point. PR 3 of the
+staged build, part a.
+**Change:** Two new storage primitive modules the receiver wiring (PR 3b) will consume:
+`AgentTelegramLedger` (append-only JSONL of sent + received audit rows) and
+`ProcessedIdStore` (bounded persistent set of recently-processed marker `id`s for Telegram
+retry / restart idempotency). Both **dark** — no caller yet; PR 3b wires the recipient
+handler at `server.ts` and uses these.
+**Files:** `src/messaging/AgentTelegramLedger.ts` (new), `src/messaging/ProcessedIdStore.ts`
+(new), `tests/unit/messaging/AgentTelegramLedger.test.ts` (new — covers both).
+
+## The seven questions
+
+1. **Over-block.** N/A — no gate. The ledger always writes; the store only blocks on a
+   recorded `id` (the idempotency guarantee).
+2. **Under-block.** Ledger writes are **best-effort + non-throwing** — an audit-write
+   failure must not crash a tick (spec note: "silent drops make Stage-B forensics painful,
+   but a crashed tick is worse"). Tested: pointing the ledger at an unwritable path → no
+   throw. The store's persistence is also best-effort (warn + continue on persist failure,
+   retry on next mark).
+3. **Level-of-abstraction fit.** Each module owns ONE thing — ledger appends rows; store
+   answers "have I seen this id." Both injectable for PR 3b's wiring + tests. JSONL append
+   is intentional (atomic at line granularity on POSIX for `<PIPE_BUF`); SafeFsExecutor's
+   atomic-write-replace is wrong for append (documented in module header so a future
+   reviewer doesn't "fix" it incorrectly).
+4. **Signal vs authority.** N/A.
+5. **Interactions — both modules are dark.** No caller, no runtime side-effect. PR 3b
+   integrates them into the recipient handler. The ReceiveAuditRow shape is the wire
+   contract for Stage-B forensics + future debugging.
+6. **External surfaces.** None new. Default paths are `{stateDir}/a2a-sent.jsonl` +
+   `{stateDir}/a2a-received.jsonl` + (PR 3b chooses) `{stateDir}/a2a-processed-ids.json`.
+   Caller may override.
+7. **Rollback cost.** Trivial — revert removes two unused modules. No data, no migration.
+
+## Convention notes
+
+- **JSONL ≠ SQLite for these two cases.** The MessageProcessingLedger header explicitly
+  prefers SQLite for dedup ledgers ("NOT a new ad-hoc JSON file") — and we follow that
+  spirit by isolating the data behind a class boundary (a SQLite swap-in is one constructor
+  away). The current JSON-file backing is justified for `ProcessedIdStore` because the
+  working set is small (bounded 10k entries / 30d), atomic-write-rewrite is cheap at that
+  size, and there's no concurrent-writer story to need WAL. For `AgentTelegramLedger`,
+  JSONL append IS the right shape (forensic trail, append-only, line-atomic).
+- **Eviction policy + the round-2 adversarial F2 surface.** The store evicts by
+  `maxEntries` (10k) OR `maxAgeMs` (30d) — whichever first. A replayer who captured an `id`
+  outside that window could re-inject it; the **defense at that layer is the marker's
+  `ts` + `skewWindowMs` (24h)** added in PR 1 (already shipped). The store's job is
+  "de-dup within the legitimate-retry window," not "absolute replay protection." Documented.
+
+## Testing
+
+8 unit tests, all green:
+- **Ledger**: appendSent + appendReceived to distinct files (+ JSONL line-per-row); drop
+  row with `dropReason` captured (the routing-matrix audit trail); **never throws** when
+  the target is unwritable (best-effort guard tested).
+- **Store**: mark + recall + persist-across-reopen; eviction by `maxAgeMs`; eviction by
+  `maxEntries` (oldest first); corrupt-file recovery (start fresh, don't crash); idempotent
+  re-mark (first-seen-ts preserved).
+- `tsc --noEmit` clean. Both modules dark (no caller).
+
+## Migration parity
+
+None — two new unwired modules. No agent-installed file changes, no config consumed yet.
+PR 3b adds the recipient handler wiring + `mentor.processedIdStorePath` (or similar) to
+config defaults; PR 3c (mentor consumer) adds the file-outbox retirement + dead-config
+removal migrations per the spec's §Migration parity.