instar 1.3.35 → 1.3.37

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/dist/monitoring/ReleaseReadinessSentinel.d.ts

@@ -0,0 +1,172 @@
+/**
+ * ReleaseReadinessSentinel — Layer B of the release-readiness-visibility spec.
+ *
+ * Watches whether a release is blocked/stalling and makes it impossible to miss.
+ * The original incident (2026-05-27): npm publishing silently stalled since
+ * v1.3.26 — green merges, green CI, no published release, no alert. The publish
+ * workflow's NEXT.md gate is a *silent skip*: a stalled release is
+ * indistinguishable from "nothing to publish". This sentinel is the missing
+ * visibility — a recurring, near-silent check that surfaces a stuck release as
+ * a single, deduped, escalating Attention item.
+ *
+ * Design (spec §4.2):
+ *   - Reads canonical `main` (FETCH_HEAD), not the local checkout, so a stale
+ *     dev branch can't produce a false "all clear".
+ *   - "Blocked" is decoupled from NEXT.md state (so Layer A's auto-draft can't
+ *     silence the alarm by clearing the file): unreleased feature/fix commits
+ *     exist AND the guide can't publish (missing/template/unreviewed), OR the
+ *     analyzer reports critical/high coverage gaps.
+ *   - Near-silent: silent below threshold (state + log only); ONE Attention
+ *     item per stall episode above it, keyed on the OLDEST unreleased commit
+ *     SHA (stable across ticks — not a resettable per-tick id), priority scaled
+ *     by backlog age, 12h hysteresis on re-raise after an auto-resolve.
+ *   - Fail-loud: any evaluation failure (fetch error, analyzer error) raises a
+ *     low-priority Attention item — never a silent catch (that would re-create
+ *     the exact bug this fixes).
+ *   - Lifecycle owner: detect → surface → auto-resolve → reap, with
+ *     resolveEpisodesInRange consulted by the publish-finalize path.
+ *   - Repo-gated: needs an analyzable instar git repo (dev/maintainer env). On
+ *     an npm-installed agent with no such repo the deps make the check inert.
+ *   - Supervision: Tier 0 (mechanical computation + fixed-template wording).
+ */
+import { EventEmitter } from 'node:events';
+/** Parsed subset of `analyze-release.js --json` the sentinel needs. */
+export interface AnalyzerReport {
+    lastTag: string;
+    commitCount: number;
+    analysis: {
+        commitClassification: {
+            features: number;
+            fixes: number;
+        };
+    };
+    guideCoverage: {
+        criticalGaps: number;
+        highGaps: number;
+    };
+}
+export interface OldestCommit {
+    sha: string;
+    dateMs: number;
+}
+export interface ReadinessEpisode {
+    /** Stable key: SHA of the oldest unreleased commit at first detection. */
+    oldestSha: string;
+    firstDetectedMs: number;
+    /** Set when an Attention item was raised (age crossed the threshold). */
+    openedMs?: number;
+    attentionId?: string;
+    lastPriority?: ReadinessPriority;
+    resolvedMs?: number;
+    resolvedReason?: 'published' | 'stale' | 'rolled-back' | 'cleared';
+}
+export interface ReadinessState {
+    episodes: ReadinessEpisode[];
+    /** Episodes resolved recently — used for the re-raise hysteresis window. */
+    recentResolves: Array<{
+        oldestSha: string;
+        resolvedMs: number;
+    }>;
+    /** Last failure-episode key we signaled, to dedupe fail-loud notices. */
+    lastFailureKey?: string;
+    lastTickAt?: number;
+    lastSignalAt?: number;
+    cacheHeadSha?: string;
+    canonicalRemoteOverridden?: boolean;
+    /** Runtime kill-switch set by POST /release-readiness/rollback. When true,
+     *  tick() no-ops without evaluating. Cleared by /release-readiness/enable. */
+    disabled?: boolean;
+    rollbackHistory?: Array<{
+        ts: number;
+        sessionId?: string;
+        sourceIp?: string;
+        reason?: string;
+    }>;
+}
+export type ReadinessPriority = 'LOW' | 'MEDIUM' | 'HIGH';
+export interface AttentionItem {
+    id: string;
+    title: string;
+    summary: string;
+    category?: string;
+    priority?: string;
+}
+export interface ReleaseReadinessSentinelDeps {
+    /** Fetch canonical main; resolve FETCH_HEAD sha. ok:false ⇒ unreachable. */
+    fetchCanonical(): Promise<{
+        ok: boolean;
+        headSha?: string;
+    }>;
+    /** Run analyze-release.js --json --ref against the canonical ref. null ⇒ error. */
+    runAnalyzer(ref: string): Promise<AnalyzerReport | null>;
+    /** Oldest unreleased feature/fix commit relative to lastTag..ref. */
+    oldestUnreleasedCommit(lastTag: string, ref: string): Promise<OldestCommit | null>;
+    /** True when the publish gate would refuse the guide (missing/template/unreviewed). */
+    guideBlocksPublish(): Promise<boolean>;
+    /** Best-effort: seed NEXT.md via Layer A (analyze-release.js --draft-guide). */
+    draftGuide(ref: string): Promise<void>;
+    /** Post an Attention item; resolves to true on delivery. */
+    postAttention(item: AttentionItem): Promise<boolean>;
+    /** Resolve an open Attention item by id. */
+    resolveAttention(id: string, reason: string): Promise<boolean>;
+    /** Load persisted state (or a fresh empty state). */
+    loadState(): ReadinessState;
+    /** Persist state atomically. */
+    saveState(state: ReadinessState): void;
+    /** Is `sha` an ancestor of `ref`? (for resolveEpisodesInRange) */
+    isAncestor(sha: string, ref: string): Promise<boolean>;
+    /** Append a structured audit line (sentinel-events.jsonl). */
+    audit(event: Record<string, unknown>): void;
+    now(): number;
+}
+export interface ReleaseReadinessSentinelConfig {
+    enabled?: boolean;
+    tickIntervalMs?: number;
+    backlogAgeDaysSilent?: number;
+    backlogAgeDaysLow?: number;
+    backlogAgeDaysMedium?: number;
+    backlogAgeDaysHigh?: number;
+    hysteresisHours?: number;
+    staleEpisodeTtlDays?: number;
+}
+export declare class ReleaseReadinessSentinel extends EventEmitter {
+    private readonly deps;
+    private readonly cfg;
+    private tickHandle;
+    constructor(deps: ReleaseReadinessSentinelDeps, cfg?: ReleaseReadinessSentinelConfig);
+    start(): void;
+    stop(): void;
+    /** Priority for a given backlog age, or null when below the silent threshold. */
+    priorityForAge(ageDays: number): ReadinessPriority | null;
+    /** The cron entry point. Top-level catch converts any error into a loud signal. */
+    tick(): Promise<void>;
+    /** Read-only snapshot of current state (for GET /release-readiness). */
+    snapshot(): ReadinessState;
+    /**
+     * Runtime kill-switch (POST /release-readiness/rollback). Disables future
+     * ticks, resolves all open Attention items, and is ITSELF loud — raises a
+     * HIGH-priority Attention item + audits — so the rollback can never be a
+     * silent way to mute the alarm (iter-3 Adversarial V5).
+     */
+    rollback(meta?: {
+        sessionId?: string;
+        sourceIp?: string;
+    }): Promise<void>;
+    /** Re-arm after a rollback. */
+    enable(): void;
+    private evaluate;
+    private isBlocked;
+    private raiseGapOnly;
+    private failLoud;
+    private resolveAll;
+    /**
+     * Called by the publish-finalize path (and the /rollback route via 'rolled-back').
+     * Resolves every open episode whose oldestSha is an ancestor of newTagSha —
+     * correct even when the oldest-unreleased SHA churned during the open window.
+     */
+    resolveEpisodesInRange(newTagSha: string, reason?: ReadinessEpisode['resolvedReason']): Promise<void>;
+    /** TTL-reap episodes/resolves so state doesn't grow unbounded. */
+    private reap;
+    static emptyState(): ReadinessState;
+}
+//# sourceMappingURL=ReleaseReadinessSentinel.d.ts.map

package/dist/monitoring/ReleaseReadinessSentinel.d.ts.map

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