instar 1.3.35 → 1.3.36

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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"}

package/dist/monitoring/ReleaseReadinessSentinel.js

@@ -0,0 +1,315 @@
+/**
+ * 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';
+const DEFAULTS = {
+    enabled: false,
+    tickIntervalMs: 6 * 60 * 60 * 1000, // 6h
+    backlogAgeDaysSilent: 2,
+    backlogAgeDaysLow: 2,
+    backlogAgeDaysMedium: 4,
+    backlogAgeDaysHigh: 7,
+    hysteresisHours: 12,
+    staleEpisodeTtlDays: 30,
+};
+const DAY_MS = 24 * 60 * 60 * 1000;
+const HOUR_MS = 60 * 60 * 1000;
+export class ReleaseReadinessSentinel extends EventEmitter {
+    deps;
+    cfg;
+    tickHandle = null;
+    constructor(deps, cfg = {}) {
+        super();
+        this.deps = deps;
+        this.cfg = { ...DEFAULTS, ...cfg };
+    }
+    start() {
+        if (!this.cfg.enabled || this.tickHandle)
+            return;
+        this.tickHandle = setInterval(() => {
+            void this.tick();
+        }, this.cfg.tickIntervalMs);
+        if (typeof this.tickHandle.unref === 'function')
+            this.tickHandle.unref();
+    }
+    stop() {
+        if (this.tickHandle) {
+            clearInterval(this.tickHandle);
+            this.tickHandle = null;
+        }
+    }
+    /** Priority for a given backlog age, or null when below the silent threshold. */
+    priorityForAge(ageDays) {
+        if (ageDays >= this.cfg.backlogAgeDaysHigh)
+            return 'HIGH';
+        if (ageDays >= this.cfg.backlogAgeDaysMedium)
+            return 'MEDIUM';
+        if (ageDays >= this.cfg.backlogAgeDaysLow)
+            return 'LOW';
+        return null;
+    }
+    /** The cron entry point. Top-level catch converts any error into a loud signal. */
+    async tick() {
+        const state = this.deps.loadState();
+        state.lastTickAt = this.deps.now();
+        if (state.disabled) {
+            this.deps.audit({ kind: 'release-readiness', event: 'tick-skipped-disabled' });
+            this.deps.saveState(state);
+            return;
+        }
+        try {
+            await this.evaluate(state);
+            this.deps.saveState(state);
+        }
+        catch (err) {
+            // Fail-loud — a silent catch here would re-create the very silent-failure
+            // bug this sentinel exists to fix.
+            await this.failLoud(state, 'tick', err);
+            this.deps.saveState(state);
+        }
+    }
+    /** Read-only snapshot of current state (for GET /release-readiness). */
+    snapshot() {
+        return this.deps.loadState();
+    }
+    /**
+     * 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).
+     */
+    async rollback(meta = {}) {
+        const state = this.deps.loadState();
+        state.disabled = true;
+        await this.resolveAll(state, 'rolled-back');
+        state.rollbackHistory ??= [];
+        state.rollbackHistory.push({ ts: this.deps.now(), sessionId: meta.sessionId, sourceIp: meta.sourceIp, reason: 'rollback' });
+        this.deps.audit({ kind: 'release-readiness', event: 'rollback', sessionId: meta.sessionId, sourceIp: meta.sourceIp });
+        await this.deps.postAttention({
+            id: 'release-readiness-rolled-back',
+            title: 'Release-readiness alarm disabled',
+            summary: `The release-readiness watchdog was disabled via /release-readiness/rollback${meta.sessionId ? ` by session ${meta.sessionId}` : ''} at ${new Date(this.deps.now()).toISOString()}. Re-enable via POST /release-readiness/enable.`,
+            category: 'degradation',
+            priority: 'HIGH',
+        });
+        this.deps.saveState(state);
+    }
+    /** Re-arm after a rollback. */
+    enable() {
+        const state = this.deps.loadState();
+        state.disabled = false;
+        this.deps.audit({ kind: 'release-readiness', event: 'enabled' });
+        this.deps.saveState(state);
+    }
+    async evaluate(state) {
+        const fetched = await this.deps.fetchCanonical();
+        if (!fetched.ok) {
+            await this.failLoud(state, 'fetch', new Error('canonical ref unreachable'));
+            return;
+        }
+        state.cacheHeadSha = fetched.headSha;
+        const ref = fetched.headSha ?? 'FETCH_HEAD';
+        // Keep NEXT.md seeded (Layer A). Best-effort: a draft failure is not a
+        // readiness failure.
+        try {
+            await this.deps.draftGuide(ref);
+        }
+        catch {
+            /* draft is advisory; the readiness signal below is what matters */
+        }
+        const report = await this.deps.runAnalyzer(ref);
+        if (!report) {
+            await this.failLoud(state, 'analyzer', new Error('analyze-release returned no report'));
+            return;
+        }
+        const blocked = this.isBlocked(report, await this.deps.guideBlocksPublish());
+        if (!blocked) {
+            // Backlog clear — resolve any open episodes.
+            await this.resolveAll(state, 'cleared');
+            // A successful evaluation clears any prior fail-loud episode.
+            state.lastFailureKey = undefined;
+            this.reap(state);
+            return;
+        }
+        const oldest = await this.deps.oldestUnreleasedCommit(report.lastTag, ref);
+        if (!oldest) {
+            // Blocked by coverage gaps but no datable commit — surface at LOW.
+            await this.raiseGapOnly(state, report);
+            this.reap(state);
+            return;
+        }
+        const ageDays = (this.deps.now() - oldest.dateMs) / DAY_MS;
+        const priority = this.priorityForAge(ageDays);
+        let episode = state.episodes.find((e) => e.oldestSha === oldest.sha && !e.resolvedMs);
+        if (!episode) {
+            episode = { oldestSha: oldest.sha, firstDetectedMs: this.deps.now() };
+            state.episodes.push(episode);
+        }
+        if (!priority) {
+            // Below the silent threshold — recorded, no message.
+            this.reap(state);
+            return;
+        }
+        // Hysteresis: don't re-raise the same sha within the window of a recent resolve.
+        const recent = state.recentResolves.find((r) => r.oldestSha === oldest.sha);
+        if (recent && this.deps.now() - recent.resolvedMs < this.cfg.hysteresisHours * HOUR_MS && !episode.openedMs) {
+            this.reap(state);
+            return;
+        }
+        if (!episode.openedMs || episode.lastPriority !== priority) {
+            const id = episode.attentionId ?? `release-readiness-${oldest.sha.slice(0, 12)}`;
+            const days = Math.floor(ageDays);
+            const delivered = await this.deps.postAttention({
+                id,
+                title: 'Release blocked — unreleased work is piling up',
+                summary: `${report.analysis.commitClassification.features + report.analysis.commitClassification.fixes} ` +
+                    `unreleased feature/fix commit(s) since ${report.lastTag}; oldest is ${days} day(s) old and publishing is blocked ` +
+                    `(NEXT.md needs review/coverage). Oldest commit ${oldest.sha.slice(0, 12)}.`,
+                category: 'degradation',
+                priority,
+            });
+            episode.openedMs = episode.openedMs ?? this.deps.now();
+            episode.attentionId = id;
+            episode.lastPriority = priority;
+            state.lastSignalAt = this.deps.now();
+            this.deps.audit({ kind: 'release-readiness', event: 'signal', oldestSha: oldest.sha, priority, ageDays: days, delivered });
+            this.emit('signal', { oldestSha: oldest.sha, priority });
+        }
+        this.reap(state);
+    }
+    isBlocked(report, guideBlocks) {
+        const featureOrFix = report.analysis.commitClassification.features + report.analysis.commitClassification.fixes;
+        const backlogBlocked = featureOrFix > 0 && guideBlocks;
+        const coverageBlocked = report.guideCoverage.criticalGaps + report.guideCoverage.highGaps > 0;
+        return backlogBlocked || coverageBlocked;
+    }
+    async raiseGapOnly(state, report) {
+        const id = 'release-readiness-coverage-gaps';
+        let episode = state.episodes.find((e) => e.oldestSha === id && !e.resolvedMs);
+        if (!episode) {
+            episode = { oldestSha: id, firstDetectedMs: this.deps.now() };
+            state.episodes.push(episode);
+        }
+        if (!episode.openedMs) {
+            const delivered = await this.deps.postAttention({
+                id,
+                title: 'Release blocked — upgrade-guide coverage gaps',
+                summary: `analyze-release reports ${report.guideCoverage.criticalGaps + report.guideCoverage.highGaps} critical/high coverage gap(s) in the upgrade guide. Publishing is blocked until they are addressed.`,
+                category: 'degradation',
+                priority: 'LOW',
+            });
+            episode.openedMs = this.deps.now();
+            episode.attentionId = id;
+            episode.lastPriority = 'LOW';
+            state.lastSignalAt = this.deps.now();
+            this.deps.audit({ kind: 'release-readiness', event: 'signal-gaps', delivered });
+        }
+    }
+    async failLoud(state, stage, err) {
+        const key = `failure:${stage}`;
+        this.deps.audit({ kind: 'release-readiness', event: 'eval-failed', stage, error: String(err) });
+        if (state.lastFailureKey === key)
+            return; // dedupe per failure episode
+        state.lastFailureKey = key;
+        await this.deps.postAttention({
+            id: `release-readiness-eval-failure-${stage}`,
+            title: 'Release-readiness check could not evaluate',
+            summary: `The release-readiness check failed at the "${stage}" stage: ${String(err)}. Last evaluated ${state.lastSignalAt ? new Date(state.lastSignalAt).toISOString() : 'never'}.`,
+            category: 'degradation',
+            priority: 'LOW',
+        });
+        state.lastSignalAt = this.deps.now();
+        this.emit('eval-failed', { stage });
+    }
+    async resolveAll(state, reason) {
+        for (const e of state.episodes) {
+            if (e.resolvedMs)
+                continue;
+            if (e.attentionId)
+                await this.deps.resolveAttention(e.attentionId, reason ?? 'cleared');
+            e.resolvedMs = this.deps.now();
+            e.resolvedReason = reason;
+            state.recentResolves.push({ oldestSha: e.oldestSha, resolvedMs: this.deps.now() });
+            this.deps.audit({ kind: 'release-readiness', event: 'resolved', oldestSha: e.oldestSha, reason });
+        }
+    }
+    /**
+     * 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.
+     */
+    async resolveEpisodesInRange(newTagSha, reason = 'published') {
+        const state = this.deps.loadState();
+        let changed = false;
+        for (const e of state.episodes) {
+            if (e.resolvedMs)
+                continue;
+            if (e.oldestSha.startsWith('release-readiness-'))
+                continue; // synthetic (gap) episodes
+            const ancestor = await this.deps.isAncestor(e.oldestSha, newTagSha);
+            if (ancestor) {
+                if (e.attentionId)
+                    await this.deps.resolveAttention(e.attentionId, reason ?? 'published');
+                e.resolvedMs = this.deps.now();
+                e.resolvedReason = reason;
+                state.recentResolves.push({ oldestSha: e.oldestSha, resolvedMs: this.deps.now() });
+                this.deps.audit({ kind: 'release-readiness', event: 'resolved-in-range', oldestSha: e.oldestSha, newTagSha, reason });
+                changed = true;
+            }
+        }
+        if (changed)
+            this.deps.saveState(state);
+    }
+    /** TTL-reap episodes/resolves so state doesn't grow unbounded. */
+    reap(state) {
+        const ttl = this.cfg.staleEpisodeTtlDays * DAY_MS;
+        const now = this.deps.now();
+        for (const e of state.episodes) {
+            if (!e.resolvedMs && now - e.firstDetectedMs > ttl) {
+                // Backlog vanished without a finalize (e.g. branch abandoned) — reap loudly.
+                e.resolvedMs = now;
+                e.resolvedReason = 'stale';
+                if (e.attentionId)
+                    void this.deps.resolveAttention(e.attentionId, 'stale');
+                this.deps.audit({ kind: 'release-readiness', event: 'reaped-stale', oldestSha: e.oldestSha });
+            }
+        }
+        state.episodes = state.episodes.filter((e) => !e.resolvedMs || now - (e.resolvedMs ?? 0) < ttl);
+        state.recentResolves = state.recentResolves.filter((r) => now - r.resolvedMs < this.cfg.hysteresisHours * HOUR_MS * 2);
+        if ((state.rollbackHistory?.length ?? 0) > 50) {
+            state.rollbackHistory = state.rollbackHistory.slice(-50);
+        }
+    }
+    static emptyState() {
+        return { episodes: [], recentResolves: [] };
+    }
+}
+//# sourceMappingURL=ReleaseReadinessSentinel.js.map

package/dist/monitoring/ReleaseReadinessSentinel.js.map

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

package/dist/monitoring/releaseReadinessWiring.d.ts

@@ -0,0 +1,54 @@
+/**
+ * releaseReadinessWiring — builds the real I/O dependencies for the
+ * ReleaseReadinessSentinel (Layer B of release-readiness-visibility).
+ *
+ * Extracted from server.ts so the dependency construction is itself
+ * unit-testable (Testing Integrity Standard: every dependency-injected
+ * component needs wiring-integrity tests proving deps are real functions, not
+ * nulls or silent no-ops).
+ *
+ * Repo-gated: the sentinel analyzes the instar git repo, which only exists in
+ * the dev/maintainer environment. `isAnalyzableRepo` lets the server decide
+ * whether to construct + start the sentinel at all on a given install.
+ *
+ * All git goes through SafeGitExecutor (audited funnel, execFileSync — no shell).
+ * Canonical-remote reads are allow-listed to github.com:JKHeadley/instar so a
+ * config override to a fork raises a HIGH-priority signal rather than silently
+ * trusting a stale fork (spec §4.2.2).
+ */
+import type { ReleaseReadinessSentinelDeps, ReadinessState, AttentionItem } from './ReleaseReadinessSentinel.js';
+/** Anchored on the known canonical host — not "any URL ending in JKHeadley/instar". */
+export declare const CANONICAL_REMOTE_RE: RegExp;
+export interface ReleaseReadinessWiringOpts {
+    /** The instar git checkout to analyze (Echo: the agent home). */
+    repoPath: string;
+    /** Path to .instar/state/release-readiness.json. */
+    statePath: string;
+    /** Path to logs/sentinel-events.jsonl. */
+    auditPath: string;
+    /** Local server port + auth for Attention posting. */
+    port: number;
+    authToken: string;
+    /** Configured canonical remote name (default: auto-detect a JKHeadley/instar remote). */
+    canonicalRemote?: string;
+    fetchTimeoutMs?: number;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}
+/** Is `repoPath` an instar git checkout we can actually analyze? */
+export declare function isAnalyzableRepo(repoPath: string): boolean;
+/** Resolve the canonical-main remote name and whether it was overridden to a non-canonical URL. */
+export declare function resolveCanonicalRemote(repoPath: string, configured?: string): {
+    remote: string;
+    overridden: boolean;
+};
+export declare function buildReleaseReadinessDeps(opts: ReleaseReadinessWiringOpts): ReleaseReadinessSentinelDeps;
+export declare function loadReadinessState(statePath: string, canonicalRemoteOverridden?: boolean): ReadinessState;
+export declare function saveReadinessState(statePath: string, state: ReadinessState): void;
+export type AttentionPoster = (item: AttentionItem) => Promise<boolean>;
+export declare function makeAttentionPoster(opts: {
+    port: number;
+    authToken: string;
+    fetchImpl?: typeof fetch;
+}): AttentionPoster;
+//# sourceMappingURL=releaseReadinessWiring.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"releaseReadinessWiring.d.ts","sourceRoot":"","sources":["../../src/monitoring/releaseReadinessWiring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,OAAO,KAAK,EACV,4BAA4B,EAC5B,cAAc,EAGd,aAAa,EACd,MAAM,+BAA+B,CAAC;AAGvC,uFAAuF;AACvF,eAAO,MAAM,mBAAmB,QAA0E,CAAC;AAE3G,MAAM,WAAW,0BAA0B;IACzC,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,yFAAyF;IACzF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,oEAAoE;AACpE,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAU1D;AAED,mGAAmG;AACnG,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,GAClB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAoBzC;AAgBD,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,0BAA0B,GAAG,4BAA4B,CAuIxG;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,yBAAyB,UAAQ,GAAG,cAAc,CAevG;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,IAAI,CAKjF;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAExE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B,GAAG,eAAe,CAclB"}