instar 1.2.33 → 1.2.35

package/dist/tunnel/TunnelNotifier.d.ts

@@ -0,0 +1,110 @@
+/**
+ * TunnelNotifier — two-channel routing of tunnel lifecycle events to
+ * the user.
+ *
+ * Per spec specs/dev-infrastructure/tunnel-failure-resilience.md Part 3.
+ *
+ * Strict channel separation (the GPT external review's CRITICAL finding):
+ *   - GROUP topic (Dashboard / Lifeline fallback / General fallback):
+ *     status text only. NEVER the URL, NEVER the PIN, NEVER a signed
+ *     view link. Anyone in the group can read those, which would defeat
+ *     the owner-only consent gate.
+ *   - OWNER DM (private bot chat with the owner principal): the actual
+ *     URL + PIN + signed view links. The only credential-bearing channel.
+ *
+ * Class-based throttling (verification finding V2 + GPT finding #5):
+ *   - action-required: NEVER throttled within an episode. Cross-episode
+ *     cooldown applies (consent prompts) but the lifecycle decides that,
+ *     not the notifier.
+ *   - state-change: light — at most one per (episode, state) pair, and
+ *     at most one per 15 minutes within an episode on re-entry of the
+ *     same state.
+ *   - noise: heavy — flapping episodes collapse into one "tunnel
+ *     unstable" message, suppressed for the rest of the episode.
+ *
+ * Dedup by transition epoch (the lifecycle's monotonic counter): the
+ * notifier never emits twice for the same epoch, even if the same
+ * event fires through multiple listeners.
+ */
+import type { TransitionEvent } from './TunnelLifecycle.js';
+import type { ProviderName } from './TunnelProvider.js';
+/** Message class — drives throttling policy. */
+export type NotificationClass = 'action-required' | 'state-change' | 'noise';
+/** Channel — drives credential-handling policy. */
+export type NotificationChannel = 'group' | 'owner-dm';
+export interface NotifierMessage {
+    channel: NotificationChannel;
+    class: NotificationClass;
+    text: string;
+    /** Episode this message belongs to (for cross-episode dedup). */
+    episodeId: string | null;
+    /** Transition epoch — never emit twice for the same epoch. */
+    epoch: number;
+}
+export interface NotifierSink {
+    /** Send a status-text message to the group topic (Dashboard preferred, Lifeline/General fallback). */
+    sendGroup(text: string): Promise<void>;
+    /** Send a credential-bearing message to the owner's private bot DM. */
+    sendOwnerDM(text: string): Promise<void>;
+}
+export interface NotifierClock {
+    now(): number;
+}
+export interface TunnelNotifierOptions {
+    sink: NotifierSink;
+    clock?: NotifierClock;
+    /** Within-episode same-state re-entry throttle (default 15 min). */
+    stateChangeMinIntervalMs?: number;
+    /** Flap threshold — N connect/drop cycles within an episode → noise-collapse. */
+    flapThreshold?: number;
+}
+export declare class TunnelNotifier {
+    private readonly sink;
+    private readonly clock;
+    private readonly stateChangeMinIntervalMs;
+    private readonly flapThreshold;
+    private lastEmittedEpoch;
+    private currentEpisodeId;
+    /** Last-emitted timestamps keyed by `<state>::<channel>` so the group
+     * pointer and the owner-DM credential delivery are throttled
+     * independently — otherwise the DM gets swallowed after the group
+     * pointer fires for the same state-change. */
+    private lastEmittedAt;
+    /** Track noise-collapse emission per episode. Once emitted, further
+     * noise messages in the same episode are suppressed. */
+    private noiseEmittedThisEpisode;
+    private flapCycles;
+    private flapCollapsed;
+    constructor(opts: TunnelNotifierOptions);
+    /**
+     * Drive the notifier from a lifecycle transition. Idempotent on the
+     * transition epoch — repeated calls with the same epoch are no-ops.
+     */
+    onTransition(e: TransitionEvent): Promise<void>;
+    /**
+     * Compose the user-facing messages for a transition. May return zero,
+     * one, or two messages (some transitions emit to BOTH channels, e.g.
+     * "back online — link in your DM" + DM with the URL).
+     *
+     * The DM credential payload is filled in by the manager via a callback
+     * (the notifier itself doesn't know URLs/PINs); for now the DM strings
+     * are placeholders that the manager substitutes before send. Future:
+     * extend onTransition signature to accept the credential payload.
+     */
+    private composeMessages;
+    /**
+     * Throttle decision per spec Part 3:
+     *   - action-required: NEVER throttled within an episode.
+     *   - state-change: at most one per (episode, state, channel) combo
+     *     within `stateChangeMinIntervalMs`. The channel scoping is
+     *     load-bearing: the group pointer and the owner-DM credential
+     *     delivery are TWO messages for the same state-change; they must
+     *     both emit, not throttle each other out.
+     *   - noise: emits at most once per episode. The flap-collapse
+     *     message goes out the first time the threshold is crossed; all
+     *     subsequent noise in the same episode is suppressed.
+     */
+    private allow;
+}
+export type { ProviderName };
+//# sourceMappingURL=TunnelNotifier.d.ts.map

package/dist/tunnel/TunnelNotifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TunnelNotifier.d.ts","sourceRoot":"","sources":["../../src/tunnel/TunnelNotifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAwB,MAAM,sBAAsB,CAAC;AAClF,OAAO,KAAK,EAAE,YAAY,EAAyB,MAAM,qBAAqB,CAAC;AAE/E,gDAAgD;AAChD,MAAM,MAAM,iBAAiB,GAAG,iBAAiB,GAAG,cAAc,GAAG,OAAO,CAAC;AAE7E,mDAAmD;AACnD,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,UAAU,CAAC;AAEvD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,mBAAmB,CAAC;IAC7B,KAAK,EAAE,iBAAiB,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,sGAAsG;IACtG,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,uEAAuE;IACvE,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,IAAI,MAAM,CAAC;CACf;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,oEAAoE;IACpE,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,iFAAiF;IACjF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAS;IAClD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IAIvC,OAAO,CAAC,gBAAgB,CAAM;IAG9B,OAAO,CAAC,gBAAgB,CAAuB;IAC/C;;;kDAG8C;IAC9C,OAAO,CAAC,aAAa,CAAkC;IACvD;4DACwD;IACxD,OAAO,CAAC,uBAAuB,CAAS;IACxC,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,aAAa,CAAS;gBAElB,IAAI,EAAE,qBAAqB;IAOvC;;;OAGG;IACG,YAAY,CAAC,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAyCrD;;;;;;;;;OASG;IACH,OAAO,CAAC,eAAe;IA6HvB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,KAAK;CAWd;AAmBD,YAAY,EAAE,YAAY,EAAE,CAAC"}

package/dist/tunnel/TunnelNotifier.js

@@ -0,0 +1,268 @@
+/**
+ * TunnelNotifier — two-channel routing of tunnel lifecycle events to
+ * the user.
+ *
+ * Per spec specs/dev-infrastructure/tunnel-failure-resilience.md Part 3.
+ *
+ * Strict channel separation (the GPT external review's CRITICAL finding):
+ *   - GROUP topic (Dashboard / Lifeline fallback / General fallback):
+ *     status text only. NEVER the URL, NEVER the PIN, NEVER a signed
+ *     view link. Anyone in the group can read those, which would defeat
+ *     the owner-only consent gate.
+ *   - OWNER DM (private bot chat with the owner principal): the actual
+ *     URL + PIN + signed view links. The only credential-bearing channel.
+ *
+ * Class-based throttling (verification finding V2 + GPT finding #5):
+ *   - action-required: NEVER throttled within an episode. Cross-episode
+ *     cooldown applies (consent prompts) but the lifecycle decides that,
+ *     not the notifier.
+ *   - state-change: light — at most one per (episode, state) pair, and
+ *     at most one per 15 minutes within an episode on re-entry of the
+ *     same state.
+ *   - noise: heavy — flapping episodes collapse into one "tunnel
+ *     unstable" message, suppressed for the rest of the episode.
+ *
+ * Dedup by transition epoch (the lifecycle's monotonic counter): the
+ * notifier never emits twice for the same epoch, even if the same
+ * event fires through multiple listeners.
+ */
+export class TunnelNotifier {
+    sink;
+    clock;
+    stateChangeMinIntervalMs;
+    flapThreshold;
+    // Dedup state. The lifecycle's epoch is monotonic per manager instance,
+    // so once we've emitted for epoch N we never re-emit for N.
+    lastEmittedEpoch = -1;
+    // Per-episode bookkeeping.
+    currentEpisodeId = null;
+    /** Last-emitted timestamps keyed by `<state>::<channel>` so the group
+     * pointer and the owner-DM credential delivery are throttled
+     * independently — otherwise the DM gets swallowed after the group
+     * pointer fires for the same state-change. */
+    lastEmittedAt = new Map();
+    /** Track noise-collapse emission per episode. Once emitted, further
+     * noise messages in the same episode are suppressed. */
+    noiseEmittedThisEpisode = false;
+    flapCycles = 0;
+    flapCollapsed = false;
+    constructor(opts) {
+        this.sink = opts.sink;
+        this.clock = opts.clock ?? { now: () => Date.now() };
+        this.stateChangeMinIntervalMs = opts.stateChangeMinIntervalMs ?? 15 * 60_000;
+        this.flapThreshold = opts.flapThreshold ?? 3;
+    }
+    /**
+     * Drive the notifier from a lifecycle transition. Idempotent on the
+     * transition epoch — repeated calls with the same epoch are no-ops.
+     */
+    async onTransition(e) {
+        // Dedup on epoch FIRST: never emit twice for the same epoch even if
+        // the listener fires multiple times.
+        if (e.epoch <= this.lastEmittedEpoch)
+            return;
+        this.lastEmittedEpoch = e.epoch;
+        // Reset per-episode bookkeeping when the episode id changes.
+        const newEpisodeId = e.episode?.episodeId ?? null;
+        if (newEpisodeId !== this.currentEpisodeId) {
+            this.currentEpisodeId = newEpisodeId;
+            this.lastEmittedAt = new Map();
+            this.noiseEmittedThisEpisode = false;
+            this.flapCycles = 0;
+            this.flapCollapsed = false;
+        }
+        // Build the message for THIS transition (if any).
+        const messages = this.composeMessages(e);
+        for (const m of messages) {
+            const allowed = this.allow(m, e.to);
+            if (!allowed)
+                continue;
+            try {
+                if (m.channel === 'group') {
+                    await this.sink.sendGroup(m.text);
+                }
+                else {
+                    await this.sink.sendOwnerDM(m.text);
+                }
+                // Update bookkeeping AFTER successful send (cheap-best-effort).
+                const key = throttleKey(e.to, m.channel);
+                this.lastEmittedAt.set(key, this.clock.now());
+                if (m.class === 'noise') {
+                    this.noiseEmittedThisEpisode = true;
+                }
+            }
+            catch {
+                // Never throw into the tunnel path — preserves existing
+                // .catch(() => {}) semantics from server.ts.
+            }
+        }
+    }
+    /**
+     * Compose the user-facing messages for a transition. May return zero,
+     * one, or two messages (some transitions emit to BOTH channels, e.g.
+     * "back online — link in your DM" + DM with the URL).
+     *
+     * The DM credential payload is filled in by the manager via a callback
+     * (the notifier itself doesn't know URLs/PINs); for now the DM strings
+     * are placeholders that the manager substitutes before send. Future:
+     * extend onTransition signature to accept the credential payload.
+     */
+    composeMessages(e) {
+        const ep = e.episode?.episodeId ?? null;
+        const reason = e.lastFailureReason;
+        const messages = [];
+        switch (e.to) {
+            case 'retrying':
+                // First Tier-1 failure — describe the cause, no DM.
+                messages.push({
+                    channel: 'group',
+                    class: 'state-change',
+                    text: `Couldn't reach the usual Cloudflare tunnel${reasonSuffix(reason)}; still retrying.`,
+                    episodeId: ep,
+                    epoch: e.epoch,
+                });
+                // Track for flap detection.
+                this.flapCycles += 1;
+                if (this.flapCycles >= this.flapThreshold && !this.flapCollapsed) {
+                    this.flapCollapsed = true;
+                    messages.push({
+                        channel: 'group',
+                        class: 'noise',
+                        text: `Tunnel is unstable right now — still working on it. I'll stop re-pinging this until something changes.`,
+                        episodeId: ep,
+                        epoch: e.epoch,
+                    });
+                }
+                break;
+            case 'active':
+                if (e.from === 'self-healing' || e.from === 'relay-active') {
+                    // Self-healed back to Tier 1.
+                    messages.push({
+                        channel: 'group',
+                        class: 'state-change',
+                        text: `Your permanent link is back. New link in your DM.`,
+                        episodeId: ep,
+                        epoch: e.epoch,
+                    });
+                    messages.push({
+                        channel: 'owner-dm',
+                        class: 'state-change',
+                        text: `__OWNER_DM_RESTORED_URL_PLACEHOLDER__`,
+                        episodeId: ep,
+                        epoch: e.epoch,
+                    });
+                }
+                else if (e.from === 'retrying') {
+                    // Cloudflare came back during retry.
+                    messages.push({
+                        channel: 'group',
+                        class: 'state-change',
+                        text: `Back online. Link in your DM.`,
+                        episodeId: ep,
+                        epoch: e.epoch,
+                    });
+                    messages.push({
+                        channel: 'owner-dm',
+                        class: 'state-change',
+                        text: `__OWNER_DM_RECOVERED_URL_PLACEHOLDER__`,
+                        episodeId: ep,
+                        epoch: e.epoch,
+                    });
+                }
+                // Other 'active' arrivals (initial startup) are non-events from the user's perspective.
+                break;
+            case 'awaiting-consent':
+                // Consent prompt: owner DM only, brief group pointer.
+                messages.push({
+                    channel: 'group',
+                    class: 'state-change',
+                    text: `Cloudflare is down. I've messaged you in DM about a possible backup.`,
+                    episodeId: ep,
+                    epoch: e.epoch,
+                });
+                messages.push({
+                    channel: 'owner-dm',
+                    class: 'action-required',
+                    text: `__OWNER_DM_CONSENT_PROMPT_PLACEHOLDER__`,
+                    episodeId: ep,
+                    epoch: e.epoch,
+                });
+                break;
+            case 'relay-active':
+                // A Tier-2 relay is up: group pointer + DM with URL + rotated PIN.
+                messages.push({
+                    channel: 'group',
+                    class: 'state-change',
+                    text: `Backup tunnel is up. New link in your DM.`,
+                    episodeId: ep,
+                    epoch: e.epoch,
+                });
+                messages.push({
+                    channel: 'owner-dm',
+                    class: 'state-change',
+                    text: `__OWNER_DM_RELAY_URL_PLACEHOLDER__`,
+                    episodeId: ep,
+                    epoch: e.epoch,
+                });
+                break;
+            case 'exhausted':
+                messages.push({
+                    channel: 'group',
+                    class: 'state-change',
+                    text: `All tunnel options are unavailable right now. I'll keep retrying Cloudflare in the background and switch back the moment it recovers — no restart needed.`,
+                    episodeId: ep,
+                    epoch: e.epoch,
+                });
+                break;
+            case 'self-healing':
+                // No user-visible message at entry. The "permanent link is back"
+                // emits on self-healing → active (above).
+                break;
+            // No notification on idle / starting transitions.
+            case 'idle':
+            case 'starting':
+                break;
+        }
+        return messages;
+    }
+    /**
+     * Throttle decision per spec Part 3:
+     *   - action-required: NEVER throttled within an episode.
+     *   - state-change: at most one per (episode, state, channel) combo
+     *     within `stateChangeMinIntervalMs`. The channel scoping is
+     *     load-bearing: the group pointer and the owner-DM credential
+     *     delivery are TWO messages for the same state-change; they must
+     *     both emit, not throttle each other out.
+     *   - noise: emits at most once per episode. The flap-collapse
+     *     message goes out the first time the threshold is crossed; all
+     *     subsequent noise in the same episode is suppressed.
+     */
+    allow(m, toState) {
+        if (m.class === 'action-required')
+            return true;
+        if (m.class === 'noise') {
+            return !this.noiseEmittedThisEpisode;
+        }
+        // state-change: keyed per (state, channel).
+        const key = throttleKey(toState, m.channel);
+        const lastAt = this.lastEmittedAt.get(key);
+        if (lastAt === undefined)
+            return true;
+        return this.clock.now() - lastAt >= this.stateChangeMinIntervalMs;
+    }
+}
+function throttleKey(state, channel) {
+    return `${state}::${channel}`;
+}
+function reasonSuffix(reason) {
+    switch (reason) {
+        case 'rate-limited': return ' (Cloudflare is rate-limiting us)';
+        case 'binary-missing': return ' (the tunnel software is missing)';
+        case 'network': return ' (network is unreachable)';
+        case 'timeout': return ' (it timed out connecting)';
+        case 'process-exit': return ' (the tunnel process exited)';
+        case 'reachability-failed': return ' (the link did not respond)';
+        default: return '';
+    }
+}
+//# sourceMappingURL=TunnelNotifier.js.map

package/dist/tunnel/TunnelNotifier.js.map

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

package/dist/tunnel/TunnelProvider.d.ts

@@ -0,0 +1,80 @@
+/**
+ * TunnelProvider — abstraction over the underlying tunnel implementation.
+ *
+ * Per spec specs/dev-infrastructure/tunnel-failure-resilience.md Part 1:
+ * the TunnelManager is the single owner of the lifecycle state machine,
+ * and each backend (cloudflared quick, cloudflared named, localtunnel,
+ * bore) implements this interface. The manager treats providers as
+ * interchangeable units; trust-tier ordering (Tier 1 vs Tier 2) and the
+ * consent gate live in the manager, NOT in the providers themselves.
+ *
+ * Two tiers:
+ *   - Tier 1: automatic, secure. Cloudflare providers. Tried silently.
+ *   - Tier 2: consent-gated relays. localtunnel, bore. Never activated
+ *     without explicit owner approval recorded against the episode.
+ *
+ * Every provider's `start()` MUST resolve only after the URL has passed
+ * a post-start reachability probe (verified by the manager via the
+ * /health endpoint through the public URL). A URL that emits from
+ * cloudflared but doesn't actually serve (e.g. localtunnel interstitial,
+ * bore.pub down) is NOT counted as `active` — that prevents a false
+ * "back online" broadcast for a dead link.
+ *
+ * The provider does NOT decide retry, fallback, or notification — those
+ * are the manager's responsibility. Provider responsibilities are
+ * narrowly: spawn the backend, surface the URL, surface a stop handle.
+ */
+/** Trust tier — Tier 1 is automatic/secure, Tier 2 is consent-gated. */
+export type ProviderTier = 1 | 2;
+/** Stable identifier the manager uses to route episode/consent records. */
+export type ProviderName = 'cloudflare-named' | 'cloudflare-quick' | 'localtunnel' | 'bore';
+export interface TunnelProviderHandle {
+    /** The public URL the provider exposes. */
+    readonly url: string;
+    /**
+     * Stop the provider. MUST escalate SIGINT → SIGKILL with PID
+     * verification (mirror the existing `forceStop()` pattern) so the
+     * manager can guarantee no relay child lingers across a self-heal
+     * switch-back. Tunnel teardown is security-load-bearing for Tier 2.
+     */
+    stop(): Promise<void>;
+}
+export interface TunnelProvider {
+    /** Stable name routed through episode/consent records and audit logs. */
+    readonly name: ProviderName;
+    /** Trust tier — manager uses this to decide whether the consent gate applies. */
+    readonly tier: ProviderTier;
+    /**
+     * True if the provider can be started in this environment without further
+     * user setup. Used by the manager to filter the provider pool BEFORE
+     * declaring `exhausted`. Reasons for `false`: required binary missing,
+     * required token/credentials not configured, OS unsupported, etc.
+     *
+     * The manager calls this once per episode (cheap signal), not per attempt.
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Start the provider against the given local port. Resolves with the
+     * URL + a stop handle when the URL is emitted by the backend. The
+     * manager performs the reachability probe AFTER resolution and before
+     * transitioning to `active`; providers MUST NOT do their own probing
+     * here (the manager owns post-start verification per spec Part 1).
+     *
+     * Implementations should reject with a structured Error whose `message`
+     * carries the classification the manager will surface to the notifier
+     * (e.g. "rate-limited (HTTP 429 / Cloudflare 1015)", "binary missing",
+     * "network unreachable", "process exited code 1"). The manager parses
+     * these strings into ProviderFailureReason classifications.
+     */
+    start(localPort: number): Promise<TunnelProviderHandle>;
+}
+/**
+ * Classification the manager applies to a provider failure for the
+ * notifier and for deciding whether to advance to the next provider.
+ *
+ * The classification is owned by the manager (not the provider) per the
+ * signal-vs-authority discipline: providers raise errors with reason
+ * strings; the manager classifies into this enum and routes accordingly.
+ */
+export type ProviderFailureReason = 'rate-limited' | 'binary-missing' | 'network' | 'process-exit' | 'timeout' | 'reachability-failed' | 'unknown';
+//# sourceMappingURL=TunnelProvider.d.ts.map

package/dist/tunnel/TunnelProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TunnelProvider.d.ts","sourceRoot":"","sources":["../../src/tunnel/TunnelProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,wEAAwE;AACxE,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,CAAC,CAAC;AAEjC,2EAA2E;AAC3E,MAAM,MAAM,YAAY,GACpB,kBAAkB,GAClB,kBAAkB,GAClB,aAAa,GACb,MAAM,CAAC;AAEX,MAAM,WAAW,oBAAoB;IACnC,2CAA2C;IAC3C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAE5B,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAE5B;;;;;;;OAOG;IACH,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAEhC;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;CACzD;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAC7B,cAAc,GACd,gBAAgB,GAChB,SAAS,GACT,cAAc,GACd,SAAS,GACT,qBAAqB,GACrB,SAAS,CAAC"}

package/dist/tunnel/TunnelProvider.js

@@ -0,0 +1,28 @@
+/**
+ * TunnelProvider — abstraction over the underlying tunnel implementation.
+ *
+ * Per spec specs/dev-infrastructure/tunnel-failure-resilience.md Part 1:
+ * the TunnelManager is the single owner of the lifecycle state machine,
+ * and each backend (cloudflared quick, cloudflared named, localtunnel,
+ * bore) implements this interface. The manager treats providers as
+ * interchangeable units; trust-tier ordering (Tier 1 vs Tier 2) and the
+ * consent gate live in the manager, NOT in the providers themselves.
+ *
+ * Two tiers:
+ *   - Tier 1: automatic, secure. Cloudflare providers. Tried silently.
+ *   - Tier 2: consent-gated relays. localtunnel, bore. Never activated
+ *     without explicit owner approval recorded against the episode.
+ *
+ * Every provider's `start()` MUST resolve only after the URL has passed
+ * a post-start reachability probe (verified by the manager via the
+ * /health endpoint through the public URL). A URL that emits from
+ * cloudflared but doesn't actually serve (e.g. localtunnel interstitial,
+ * bore.pub down) is NOT counted as `active` — that prevents a false
+ * "back online" broadcast for a dead link.
+ *
+ * The provider does NOT decide retry, fallback, or notification — those
+ * are the manager's responsibility. Provider responsibilities are
+ * narrowly: spawn the backend, surface the URL, surface a stop handle.
+ */
+export {};
+//# sourceMappingURL=TunnelProvider.js.map

package/dist/tunnel/TunnelProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TunnelProvider.js","sourceRoot":"","sources":["../../src/tunnel/TunnelProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.2.33",
+  "version": "1.2.35",
   "description": "Persistent autonomy infrastructure for AI agents",
   "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-22T20:34:00.772Z",
-  "instarVersion": "1.2.33",
+  "generatedAt": "2026-05-22T22:17:56.523Z",
+  "instarVersion": "1.2.35",
   "entryCount": 191,
   "entries": {
     "hook:session-start": {

package/upgrades/1.2.34.md

@@ -0,0 +1,84 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+<!-- patch = behavior fix, no new capability, no breaking change -->
+
+## What Changed
+
+**feat(tone-gate): add B15_CONTEXT_DEATH_STOP — block outbound "fresh-
+session / hand-off" framing on in-flight work.**
+
+instar's `MessagingToneGate` already runs on every outbound user
+message and blocks fourteen classes of leakage (B1–B14 — CLI commands,
+file paths, jargon dumps, health-alert internals, style mismatch,
+etc.). This adds a fifteenth rule, **B15_CONTEXT_DEATH_STOP**, that
+catches a specific failure mode of the agent: proposing to pause, stop,
+or hand off the current in-flight work for a context-window /
+fresh-session / end-of-session reason rather than a legitimate stop
+reason.
+
+The pattern is documented in the CLAUDE.md "Context-Death Self-Stop"
+anti-pattern section, and reinforced by multiple memory entries
+(`feedback_scope_hook_is_grounding_not_termination`,
+`feedback_no_deferrals`, `feedback_finish_means_merge`, etc.). Despite
+the documentation, the slip kept recurring. Per instar's foundational
+"Structure beats willpower" principle, this needs a structural guard
+that catches the language at send-time.
+
+B15 is an LLM-gate rule (the existing tone-gate authority). It lists
+literal pattern markers ("fresh session," "next session," "tail of
+this session," "hand off cleanly," "pick this up later," etc.) AND
+legitimate-stop carve-outs that pass unblocked (real design question
+only the operator can answer, real blocker, real error, completion
+report on user-requested scope). The LLM combines the markers with
+conversational context and the carve-outs to make the block/pass call.
+
+When B15 fires, the standard tone-gate UX applies: the candidate is
+rejected with rule id B15, an issue summary, and a suggestion. The
+agent has to either delete the handoff framing and continue working
+or supply an explicit legitimate-stop reason.
+
+## Evidence
+
+The change is one entry added to `VALID_RULES`, one new section in
+the gate's prompt, and one line updated in the response-format note
+listing valid rule ids. Nine unit tests in
+`tests/unit/messaging-tone-gate-b15.test.ts` verify:
+
+1. The prompt always carries the B15 rule definition for every review.
+2. The prompt carries the literal pattern markers (fresh session, next
+   session, tail of this session, hand off cleanly, pick this up later).
+3. The prompt documents the legitimate-stop carve-outs (completion
+   report, genuine error / blocker).
+4. The response-format rule list includes B15.
+5. An LLM response citing B15 is accepted as a valid block (not
+   fail-opened as `invalidRule`).
+6. A completion-report message passes through unchanged when the LLM
+   returns pass.
+7. A genuine-blocker message passes through unchanged.
+8. A topic-split / continuation message passes through unchanged.
+9. The drift-detection still rejects unknown rule ids (no widening
+   of the gate to arbitrary ids).
+
+All 27 existing `MessagingToneGate.test.ts` tests still pass; all 8
+existing `messaging-tone-gate-health-alerts.test.ts` tests still pass.
+The TypeScript build is clean; lint is clean.
+
+## What to Tell Your User
+
+Your agent now has one more safety net on the messages it sends you.
+The new check looks for moments where the agent is about to write some
+version of "let me pick this up in a fresh session" or "I'll hand this
+off cleanly" while the work you asked for isn't actually done yet — and
+quietly blocks that message before it reaches you. The agent has to
+either delete the bail-out framing and keep working, or cite a real
+reason for stopping. You should notice the agent doing less of that
+pattern. Nothing changes about messages where the agent has a real
+question, a real blocker, a real error, or actually finished the work.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| B15 tone-gate rule catches outbound context-death stop framing | Automatic — runs on every outbound user message via MessagingToneGate |
+| B15 has explicit legitimate-stop carve-outs | Automatic — real question / real blocker / real error / completion report pass unblocked |