@reefclaw/openclaw-plugin 0.1.24 → 0.1.26

package/bridge/index.js

@@ -16,7 +16,10 @@ import { MockProvider } from './providers/mock.js';
 import { GatewayProvider } from './providers/gateway.js';
 import { resolveConfig } from './config.js';
 import { resolveGatewayConfig, validateGatewayConfig } from './gateway/gateway-config.js';
+import { ShockWakePoller } from './shock-wake.js';
+import { HeartbeatRunRecorder } from './heartbeat-runs.js';
 import { runSetup } from './setup.js';
+import { resolveRelayInstanceId } from './utils/instance-id.js';
 const TAG = 'main';
 // ---- Load .env file (skill/.env only) ----
 function loadEnvFile() {
@@ -191,6 +194,7 @@ async function main() {
     }
     // Create provider
     let provider;
+    let intelligenceUrlForWakes;
     if (args.provider === 'mock') {
         logger.info(TAG, 'Using MockProvider');
         provider = new MockProvider();
@@ -217,14 +221,41 @@ async function main() {
         gwConfig.connectionToken = token;
         logger.info(TAG, `Using GatewayProvider (url=${gwConfig.gatewayUrl}, symbol=${gwConfig.symbol})`);
         provider = new GatewayProvider(gwConfig);
+        intelligenceUrlForWakes = gwConfig.intelligenceUrl;
     }
     // Create bridge
     const connectorConfig = {
         relayUrl,
         userId,
         token,
+        // Stable per-install id → the relay's skill-slot admission recognises a
+        // same-box restart (instant takeover) vs a second box (rejected 4011).
+        instanceId: resolveRelayInstanceId(),
     };
     const bridge = new Bridge(provider, connectorConfig);
+    // Shock-wake poller (WS3, docs/MARKET_ADAPTIVITY_PLAN.md) — watches intel's
+    // /api/shocks (the WS2 change-of-character flags) and delivers an
+    // out-of-band re-evaluation turn to the agent on a genuine market shift.
+    // Inert until the central gate agent_config.gates.shockWake leaves 'off'.
+    const shockWake = intelligenceUrlForWakes
+        ? new ShockWakePoller({ provider, token, intelligenceUrl: intelligenceUrlForWakes })
+        : null;
+    if (shockWake) {
+        // Delivery confirmation: any agent turn STARTING proves the main-session
+        // lane is alive — the gateway ack alone cannot (swallowed-turn class).
+        provider.on('chatMessageStart', () => shockWake.noteAssistantActivity());
+    }
+    // Heartbeat flight recorder — records what every beat actually DID (tool
+    // calls + results, report, model, raw token counts) from the isolated cron
+    // session's transcript, posts it to the webapp journal, and feeds the
+    // dashboard's last-beat summary + model-health dot. Gateway provider only
+    // (the mock has no OpenClaw sessions dir). Kill-switch: RC_HEARTBEAT_RECORDER=off.
+    const recorderOff = (process.env.RC_HEARTBEAT_RECORDER ?? 'on').trim().toLowerCase() === 'off';
+    const heartbeatRecorder = provider instanceof GatewayProvider && !recorderOff
+        ? new HeartbeatRunRecorder({ source: provider, token })
+        : null;
+    if (recorderOff)
+        logger.info(TAG, 'Heartbeat flight recorder disabled (RC_HEARTBEAT_RECORDER=off)');
     // Handle graceful shutdown
     let shuttingDown = false;
     async function shutdown(signal) {
@@ -239,6 +270,8 @@ async function main() {
             }
             catch { /* best-effort */ }
         }
+        shockWake?.stop();
+        heartbeatRecorder?.stop();
         bridge.stop();
         // Allow 1s for final cleanup before force exit
         setTimeout(() => process.exit(0), 1000);
@@ -248,5 +281,7 @@ async function main() {
     // Start
     logger.info(TAG, `Starting ReefClaw skill (provider=${args.provider}, relay=${relayUrl})`);
     bridge.start();
+    shockWake?.start();
+    heartbeatRecorder?.start();
 }
 main();

package/bridge/model-health.d.ts

@@ -0,0 +1,37 @@
+export type ModelHealthLevel = 'ok' | 'degraded' | 'error';
+export interface ModelHealth {
+    level: ModelHealthLevel;
+    /** Machine reason (a FailoverReason, 'model_fallback', 'consecutive_errors'). */
+    reason: string | null;
+    /** Human detail (error text, fallback description), redacted upstream. */
+    detail: string | null;
+    /** Epoch ms of the evidence this verdict rests on. */
+    atMs: number;
+    model: string | null;
+}
+/** FailoverReasons that do not self-heal — the operator must act. */
+export declare const HARD_REASONS: ReadonlySet<string>;
+/** FailoverReasons that usually clear on their own (quota windows, outages). */
+export declare const SOFT_REASONS: ReadonlySet<string>;
+export interface ModelHealthInputs {
+    /** The most recently recorded heartbeat run (flight recorder). */
+    lastRun?: {
+        status: string;
+        errorReason?: string | null;
+        error?: string | null;
+        model?: string | null;
+        endedAtMs?: number | null;
+        fallbackSteps?: number;
+        modelChanges?: number;
+    } | null;
+    /** The heartbeat job's cron state (`cron.list`). */
+    cron?: {
+        consecutiveErrors: number;
+        lastErrorReason?: string | null;
+        lastError?: string | null;
+        lastRunStatus?: string | null;
+        lastRunAtMs?: number | null;
+    } | null;
+    now: number;
+}
+export declare function deriveModelHealth(i: ModelHealthInputs): ModelHealth;

package/bridge/model-health.js

@@ -0,0 +1,97 @@
+// Model health — is the LLM behind the agent actually answering? (pure)
+//
+// Two incident classes motivated this: a Codex quota death (2026-06-07) and a
+// self-inflicted harness/provider mismatch (2026-07-26) both took the agent
+// dark for hours-to-days while the dashboard looked healthy. The gateway
+// classifies every failed model call with a FailoverReason (vendored
+// `embedded-agent-helpers/types.ts`) and persists it on the cron job state
+// (`lastErrorReason`) and the run log (`errorReason`); auth failures fall back
+// SILENTLY to the next model (docs/CLAUDE/agent-runtime.md §4), format
+// failures kill every turn with no fallback (§1). This derives one dot from
+// those signals so the operator sees "model degraded/erroring" instead of
+// inferring it from a stalled last-decision clock.
+//
+// Levels:
+//   error     — a reason that will not self-heal (auth_permanent, format,
+//               model_not_found, billing), or ≥2 consecutive model-classified
+//               failures.
+//   degraded  — a recoverable model reason on the last run (auth, rate_limit,
+//               overloaded, server_error, timeout, …) or a fallback / model
+//               change observed inside the last beat.
+//   ok        — nothing model-related is wrong. A run error WITHOUT a
+//               FailoverReason (e.g. a delivery-target error) stays 'ok' here:
+//               the heartbeat banner owns non-model failures.
+/** FailoverReasons that do not self-heal — the operator must act. */
+export const HARD_REASONS = new Set(['auth_permanent', 'format', 'model_not_found', 'billing']);
+/** FailoverReasons that usually clear on their own (quota windows, outages). */
+export const SOFT_REASONS = new Set([
+    'auth',
+    'rate_limit',
+    'overloaded',
+    'server_error',
+    'timeout',
+    'session_expired',
+    'empty_response',
+    'no_error_details',
+    'unclassified',
+    'unknown',
+]);
+function clip(s, n = 200) {
+    if (typeof s !== 'string')
+        return null;
+    const t = s.trim();
+    if (!t)
+        return null;
+    return t.length > n ? `${t.slice(0, n)}…` : t;
+}
+export function deriveModelHealth(i) {
+    const run = i.lastRun ?? null;
+    const cron = i.cron ?? null;
+    const model = run?.model ?? null;
+    const cronReason = cron?.lastRunStatus === 'error' ? cron.lastErrorReason ?? null : null;
+    const runReason = run?.status === 'error' ? run.errorReason ?? null : null;
+    const consecutive = cron?.consecutiveErrors ?? 0;
+    // Prefer whichever piece of evidence is newer.
+    const cronAt = cron?.lastRunAtMs ?? 0;
+    const runAt = run?.endedAtMs ?? 0;
+    const atMs = Math.max(cronAt, runAt) || i.now;
+    const hard = [cronReason, runReason].find((r) => r && HARD_REASONS.has(r)) ?? null;
+    if (hard) {
+        return {
+            level: 'error',
+            reason: hard,
+            detail: clip(cronReason === hard ? cron?.lastError : run?.error) ?? `model ${hard}`,
+            atMs,
+            model,
+        };
+    }
+    const anyReason = cronReason ?? runReason;
+    if (anyReason && consecutive >= 2) {
+        return {
+            level: 'error',
+            reason: 'consecutive_errors',
+            detail: clip(cron?.lastError ?? run?.error) ?? `${consecutive} consecutive model failures (${anyReason})`,
+            atMs,
+            model,
+        };
+    }
+    if (anyReason && (SOFT_REASONS.has(anyReason) || !HARD_REASONS.has(anyReason))) {
+        return {
+            level: 'degraded',
+            reason: anyReason,
+            detail: clip(cronReason ? cron?.lastError : run?.error) ?? `model ${anyReason}`,
+            atMs,
+            model,
+        };
+    }
+    if (run && ((run.fallbackSteps ?? 0) > 0 || (run.modelChanges ?? 0) > 0)) {
+        return {
+            level: 'degraded',
+            reason: 'model_fallback',
+            detail: `${run.fallbackSteps ?? 0} fallback step(s), ${run.modelChanges ?? 0} model change(s) in the last beat`,
+            atMs,
+            model,
+        };
+    }
+    return { level: 'ok', reason: null, detail: null, atMs, model };
+}

package/bridge/provider.d.ts

@@ -1,4 +1,4 @@
-import type { EmergencyAction, ReconciliationSnapshot, TickerData, CandleData, OrderUpdatePayload, AgentStateData, RiskUpdatePayload, ChatMessage, MarketStructureData, CryptoMetricsData, VolumeAnalysisData, TradeJournalEntry, RegimeData, SignalData, MissionData, AnalyticsData, ShadowComparisonData, TradingModeData, DecisionTraceData } from './types.js';
+import type { EmergencyAction, ReconciliationSnapshot, TickerData, CandleData, OrderUpdatePayload, AgentStateData, RiskUpdatePayload, ChatMessage, MarketStructureData, CryptoMetricsData, VolumeAnalysisData, TradeJournalEntry, RegimeData, SignalData, MissionData, AnalyticsData, ShadowComparisonData, TradingModeData, DecisionTraceData, AgentRunLifecycleData } from './types.js';
 import type { TradingMode } from '@reefclaw/shared';
 import type { ConnectorUpdateOutcome } from './providers/connector-update.js';
 /** Per-venue credential shapes for the operator set/test RPCs. Binance is an
@@ -126,6 +126,10 @@ export interface ProviderEvents {
     tradingModeUpdate: (data: TradingModeData) => void;
     /** Decision trace update (Phase 9c) */
     decisionTraceUpdate: (data: DecisionTraceData) => void;
+    /** An agent turn started/ended/errored, with the gateway's session key so a
+     *  heartbeat (cron) turn is distinguishable from a chat turn. Local-only
+     *  (not forwarded to the relay); consumed by the heartbeat flight recorder. */
+    agentRunLifecycle: (data: AgentRunLifecycleData) => void;
 }
 export type ProviderEventName = keyof ProviderEvents;
 /**

package/bridge/providers/gateway.d.ts

@@ -1,5 +1,6 @@
 import type { OpenClawProvider, ProviderEvents, ProviderEventName, ExchangeCredentialsRequest, HlProvisionOutcome, HlAgentWalletStatusOutcome, HlSubmitApprovalOutcome } from '../provider.js';
-import type { EmergencyAction, ReconciliationSnapshot, TradingMode } from '../types.js';
+import type { EmergencyAction, ReconciliationSnapshot, TradingMode, AgentRunLifecycleData } from '../types.js';
+import type { CronRunLogLite, HeartbeatRunRecord } from '../heartbeat-transcript.js';
 import type { GatewayConfig } from '../gateway/gateway-config.js';
 import { type GetBracketConfigOutcome, type SetBracketRequirementOutcome, type BracketRequirementFlag, type SetTradingModeOutcome, type SetExchangeCredentialsOutcome, type TestExchangeCredentialsOutcome, type ClearExchangeCredentialsOutcome } from './onboarding-commands.js';
 import { type ConnectorUpdateOutcome } from './connector-update.js';
@@ -56,6 +57,14 @@ export declare class GatewayProvider implements OpenClawProvider {
     private heartbeatHealth?;
     private heartbeatHealthReadAtMs;
     private heartbeatHealthRefreshing;
+    /** The heartbeat cron job's id (from cron.list) — `cron.runs` needs it. */
+    private heartbeatJobId?;
+    /** Last recorded heartbeat run (flight recorder) — dashboard summary. */
+    private lastHeartbeat?;
+    /** Model-health inputs from the last recorded run (kept apart from the
+     *  summary so the verdict can be re-derived when cron state changes). */
+    private lastHeartbeatRunForHealth?;
+    private modelHealth?;
     private lastTicker;
     private positions;
     private balance;
@@ -395,6 +404,21 @@ export declare class GatewayProvider implements OpenClawProvider {
      *  refresh is in flight. Fire-and-forget: the RPC completion re-emits
      *  agent_state, so callers stay synchronous. */
     private maybeRefreshHeartbeatHealth;
+    /** The gateway's cron run log for the heartbeat job (`cron.runs`, newest
+     *  first), normalised to the recorder's shape. Returns null when the RPC or
+     *  the job id is unavailable (older gateway / scope) — the recorder then
+     *  falls back to transcript-only records. Token counts here are RAW counts. */
+    fetchCronRuns(limit?: number): Promise<CronRunLogLite[] | null>;
+    private loggedCronRunsProbe;
+    /** A heartbeat run was recorded — keep a compact summary for the dashboard
+     *  header, re-derive model health, and re-emit agent_state. */
+    noteHeartbeatRun(record: HeartbeatRunRecord): void;
+    /** Active trading book for the record's mode tag (matches the webapp's
+     *  modeToBook: LIVE/MICRO_LIVE → live, everything else → paper). */
+    getTradingBook(): 'paper' | 'live';
+    /** Subscribe to agent turn lifecycle events; returns an unsubscribe. */
+    onAgentRunLifecycle(listener: (d: AgentRunLifecycleData) => void): () => void;
+    private recomputeModelHealth;
     /** Merge newly-resolved identity fields into the cache. Returns true if anything changed. */
     private mergeAgentIdentity;
     /**

package/bridge/providers/gateway.js

@@ -6,6 +6,7 @@ import { join } from 'path';
 import { homedir } from 'os';
 import { logger, formatError } from '../logger.js';
 import { isTradingMode } from '../types.js';
+import { deriveModelHealth } from '../model-health.js';
 import { handshakeLacksWriteScope, relaxGatewayDeviceAuth } from '../config.js';
 import { toIntelSymbol } from '@reefclaw/shared';
 import { GatewayHttpClient } from '../gateway/gateway-http-client.js';
@@ -175,6 +176,14 @@ export class GatewayProvider {
     heartbeatHealth;
     heartbeatHealthReadAtMs = 0;
     heartbeatHealthRefreshing = false;
+    /** The heartbeat cron job's id (from cron.list) — `cron.runs` needs it. */
+    heartbeatJobId;
+    /** Last recorded heartbeat run (flight recorder) — dashboard summary. */
+    lastHeartbeat;
+    /** Model-health inputs from the last recorded run (kept apart from the
+     *  summary so the verdict can be re-derived when cron state changes). */
+    lastHeartbeatRunForHealth;
+    modelHealth;
     lastTicker = null;
     positions = [];
     balance = { currency: 'USDT', total: 0, available: 0, locked: 0 };
@@ -318,6 +327,7 @@ export class GatewayProvider {
         shadowComparison: new Set(),
         tradingModeUpdate: new Set(),
         decisionTraceUpdate: new Set(),
+        agentRunLifecycle: new Set(),
     };
     constructor(config) {
         this.config = config;
@@ -1368,6 +1378,21 @@ export class GatewayProvider {
     onAgentEvent(payload) {
         if (!this.started || !this.eventParser)
             return;
+        // Turn lifecycle WITH the session key — the heartbeat flight recorder
+        // keys off `agent:main:cron:…` to scan the beat's transcript right after
+        // it ends. Fired before parsing so it never depends on parser state.
+        if (payload.stream === 'lifecycle') {
+            const phase = payload.data?.phase;
+            if (phase === 'start' || phase === 'end' || phase === 'error') {
+                this.fire('agentRunLifecycle', {
+                    runId: payload.runId,
+                    phase,
+                    ...(payload.sessionKey ? { sessionKey: payload.sessionKey } : {}),
+                    ...(payload.sessionId ? { sessionId: payload.sessionId } : {}),
+                    at: Date.now(),
+                });
+            }
+        }
         const parsed = this.eventParser.parseAgentEvent(payload);
         for (const evt of parsed) {
             // Track order/cancel rates for risk computation
@@ -2118,6 +2143,9 @@ export class GatewayProvider {
                 this.heartbeatSeconds = secs;
                 this.heartbeatReadAtMs = Date.now();
             }
+            const jobId = hb?.id;
+            if (typeof jobId === 'string' && jobId)
+                this.heartbeatJobId = jobId;
             const state = hb?.state;
             if (!state || typeof state !== 'object')
                 return;
@@ -2126,18 +2154,23 @@ export class GatewayProvider {
                 consecutiveErrors: typeof s.consecutiveErrors === 'number' && s.consecutiveErrors >= 0 ? s.consecutiveErrors : 0,
                 lastRunAtMs: typeof s.lastRunAtMs === 'number' ? s.lastRunAtMs : undefined,
                 lastRunStatus: typeof s.lastRunStatus === 'string' ? s.lastRunStatus : undefined,
+                lastErrorReason: typeof s.lastErrorReason === 'string' ? s.lastErrorReason : undefined,
+                lastError: typeof s.lastError === 'string' ? s.lastError.slice(0, 300) : undefined,
             };
             const prev = this.heartbeatHealth;
             const changed = !prev ||
                 prev.consecutiveErrors !== next.consecutiveErrors ||
                 prev.lastRunAtMs !== next.lastRunAtMs ||
-                prev.lastRunStatus !== next.lastRunStatus;
+                prev.lastRunStatus !== next.lastRunStatus ||
+                prev.lastErrorReason !== next.lastErrorReason;
             this.heartbeatHealth = next;
             this.heartbeatHealthReadAtMs = Date.now();
             if (changed) {
                 if (next.consecutiveErrors > 0) {
-                    logger.warn(TAG, `Heartbeat health: ${next.consecutiveErrors} consecutive error(s), lastStatus=${next.lastRunStatus ?? 'unknown'}`);
+                    logger.warn(TAG, `Heartbeat health: ${next.consecutiveErrors} consecutive error(s), lastStatus=${next.lastRunStatus ?? 'unknown'}` +
+                        (next.lastErrorReason ? ` reason=${next.lastErrorReason}` : ''));
                 }
+                this.recomputeModelHealth();
                 this.emitAgentState();
             }
         }
@@ -2158,6 +2191,134 @@ export class GatewayProvider {
             return;
         void this.refreshHeartbeatHealth();
     }
+    // ---- Heartbeat flight recorder hooks (skill/src/heartbeat-runs.ts) ----
+    /** The gateway's cron run log for the heartbeat job (`cron.runs`, newest
+     *  first), normalised to the recorder's shape. Returns null when the RPC or
+     *  the job id is unavailable (older gateway / scope) — the recorder then
+     *  falls back to transcript-only records. Token counts here are RAW counts. */
+    async fetchCronRuns(limit = 25) {
+        const ws = this.wsClient;
+        if (!ws)
+            return null;
+        if (!this.heartbeatJobId) {
+            await this.refreshHeartbeatHealth();
+            if (!this.heartbeatJobId)
+                return null;
+        }
+        let resp;
+        try {
+            resp = await ws.sendRpc('cron.runs', { jobId: this.heartbeatJobId, limit, sortDir: 'desc' });
+        }
+        catch (err) {
+            logger.debug(TAG, `cron.runs RPC failed: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+        const entries = resp?.entries;
+        if (!Array.isArray(entries)) {
+            if (!this.loggedCronRunsProbe) {
+                this.loggedCronRunsProbe = true;
+                const keys = resp && typeof resp === 'object' ? Object.keys(resp).join(',') : typeof resp;
+                logger.info(TAG, `cron.runs probe: unexpected shape keys=[${keys}] — token counts fall back to transcripts`);
+            }
+            return null;
+        }
+        if (!this.loggedCronRunsProbe) {
+            this.loggedCronRunsProbe = true;
+            const first = entries[0] && typeof entries[0] === 'object' ? Object.keys(entries[0]).join(',') : '(empty)';
+            logger.info(TAG, `cron.runs probe: ${entries.length} entries, keys=[${first}]`);
+        }
+        const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+        const str = (v) => (typeof v === 'string' && v ? v : null);
+        return entries.map((raw) => {
+            const e = (raw && typeof raw === 'object' ? raw : {});
+            const u = (e.usage && typeof e.usage === 'object' ? e.usage : null);
+            return {
+                sessionId: str(e.sessionId),
+                runId: str(e.runId),
+                status: str(e.status),
+                error: str(e.error),
+                errorReason: str(e.errorReason),
+                runAtMs: num(e.runAtMs) ?? num(e.ts),
+                durationMs: num(e.durationMs),
+                model: str(e.model),
+                provider: str(e.provider),
+                usage: u
+                    ? {
+                        input: num(u.input_tokens) ?? num(u.input),
+                        output: num(u.output_tokens) ?? num(u.output),
+                        cacheRead: num(u.cache_read_tokens) ?? num(u.cacheRead),
+                        cacheWrite: num(u.cache_write_tokens) ?? num(u.cacheWrite),
+                        total: num(u.total_tokens) ?? num(u.total) ?? num(u.totalTokens),
+                    }
+                    : null,
+            };
+        });
+    }
+    loggedCronRunsProbe = false;
+    /** A heartbeat run was recorded — keep a compact summary for the dashboard
+     *  header, re-derive model health, and re-emit agent_state. */
+    noteHeartbeatRun(record) {
+        this.lastHeartbeat = {
+            runId: record.runId,
+            startedAtMs: record.startedAtMs,
+            endedAtMs: record.endedAtMs,
+            durationMs: record.durationMs,
+            status: record.status,
+            toolCallCount: record.toolCallCount,
+            toolErrorCount: record.toolErrorCount,
+            tokensTotal: record.tokens.total,
+            tokensInput: record.tokens.input,
+            tokensOutput: record.tokens.output,
+            model: record.model,
+        };
+        this.lastHeartbeatRunForHealth = {
+            status: record.status,
+            errorReason: record.errorReason,
+            error: record.error,
+            model: record.model,
+            endedAtMs: record.endedAtMs,
+            fallbackSteps: record.modelEvents.filter((e) => e.kind === 'fallback_step').length,
+            modelChanges: record.modelEvents.filter((e) => e.kind === 'model_change').length,
+        };
+        this.recomputeModelHealth();
+        this.emitAgentState();
+    }
+    /** Active trading book for the record's mode tag (matches the webapp's
+     *  modeToBook: LIVE/MICRO_LIVE → live, everything else → paper). */
+    getTradingBook() {
+        return this.tradingMode === 'LIVE' || this.tradingMode === 'MICRO_LIVE' ? 'live' : 'paper';
+    }
+    /** Subscribe to agent turn lifecycle events; returns an unsubscribe. */
+    onAgentRunLifecycle(listener) {
+        this.on('agentRunLifecycle', listener);
+        return () => this.off('agentRunLifecycle', listener);
+    }
+    recomputeModelHealth() {
+        const hb = this.heartbeatHealth;
+        const next = deriveModelHealth({
+            lastRun: this.lastHeartbeatRunForHealth ?? null,
+            cron: hb
+                ? {
+                    consecutiveErrors: hb.consecutiveErrors,
+                    lastErrorReason: hb.lastErrorReason ?? null,
+                    lastError: hb.lastError ?? null,
+                    lastRunStatus: hb.lastRunStatus ?? null,
+                    lastRunAtMs: hb.lastRunAtMs ?? null,
+                }
+                : null,
+            now: Date.now(),
+        });
+        const prev = this.modelHealth;
+        if (!prev || prev.level !== next.level || prev.reason !== next.reason) {
+            if (next.level !== 'ok') {
+                logger.warn(TAG, `Model health ${next.level}: ${next.reason ?? ''} ${next.detail ?? ''}`.trim());
+            }
+            else if (prev && prev.level !== 'ok') {
+                logger.info(TAG, 'Model health recovered: ok');
+            }
+        }
+        this.modelHealth = next;
+    }
     /** Merge newly-resolved identity fields into the cache. Returns true if anything changed. */
     mergeAgentIdentity(found) {
         let changed = false;
@@ -2349,6 +2510,10 @@ export class GatewayProvider {
                         },
                     }
                     : {}),
+                // Flight recorder: absent until the first beat is recorded → payload
+                // stays byte-identical to the pre-feature shape until then.
+                ...(this.lastHeartbeat ? { lastHeartbeat: this.lastHeartbeat } : {}),
+                ...(this.modelHealth ? { modelHealth: this.modelHealth } : {}),
             },
         };
     }

package/bridge/providers/mock.js

@@ -39,6 +39,7 @@ export class MockProvider {
         shadowComparison: new Set(),
         tradingModeUpdate: new Set(),
         decisionTraceUpdate: new Set(),
+        agentRunLifecycle: new Set(),
     };
     // ---- Risk limits ----
     RISK_LIMITS = {

package/bridge/shock-wake.d.ts

@@ -0,0 +1,80 @@
+export type ShockWakeMode = 'off' | 'shadow' | 'on';
+export interface ShockEntry {
+    symbol: string;
+    time: string;
+    flags: string[];
+    shock30mAtr: number;
+    range30mAtr: number;
+    return1hPct: number;
+    return4hPct: number;
+    tape4hAtr: number;
+    regime: string;
+    summary?: string;
+}
+/** 'BTCUSDT' / 'HL_BTC' / 'BTC/USDC' → 'BTC'. Best-effort market vocabulary
+ *  for the wake message — never used to address an order. */
+export declare function coinOf(intelSymbol: string): string;
+/** Parse gates.shockWake off the raw /api/internal/config payload. Central-only
+ *  gate — absent/garbage → 'off'. */
+export declare function parseShockWakeGate(raw: unknown): ShockWakeMode;
+export interface WakeAssessment {
+    wake: boolean;
+    reason?: 'leader_shock' | 'broad_shock';
+    /** Fresh 'shock'-flagged entries, extreme-first (as served). */
+    shocked: ShockEntry[];
+}
+/** Pure wake-worthiness rule. `nowMs` gates staleness. Broad rule (2026-09-06):
+ *  ≥`minBroadCount` distinct coins shocked, OR ≥3 when a major participates. */
+export declare function assessWakeWorthiness(shocks: ShockEntry[], nowMs: number, minBroadCount?: number): WakeAssessment;
+/** The out-of-band agent turn. Clearly machine-labeled (never impersonates the
+ *  operator), mandates re-evaluation, orders nothing. */
+export declare function buildWakeMessage(a: WakeAssessment): string;
+export interface ShockWakeOpts {
+    provider: {
+        handleChat(content: string): Promise<{
+            received: boolean;
+            error?: string;
+        }>;
+    };
+    token: string;
+    intelligenceUrl: string;
+    webappUrl?: string;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}
+export declare class ShockWakePoller {
+    private readonly opts;
+    private mode;
+    private pollTimer;
+    private gateTimer;
+    private lastWakeAtMs;
+    private wakesToday;
+    private wakeDayUtc;
+    private polling;
+    private readonly pollMs;
+    private readonly gatePollMs;
+    private readonly cooldownMs;
+    private readonly dailyCap;
+    private readonly minBroad;
+    private readonly replyTimeoutMs;
+    private lastAssistantAtMs;
+    private awaitingSinceMs;
+    private awaitingDeadlineMs;
+    private suspectedSwallows;
+    constructor(opts: ShockWakeOpts);
+    start(): void;
+    stop(): void;
+    getMode(): ShockWakeMode;
+    /** Fed by the bridge from provider `chatMessageStart` — any agent turn
+     *  beginning counts (the wake's reply, or an operator chat's; either proves
+     *  the lane is alive, which is what the swallow check needs). */
+    noteAssistantActivity(atMs?: number): void;
+    /** Suspected-swallow count this process (test/telemetry seam). */
+    getSuspectedSwallows(): number;
+    private checkPendingReply;
+    private refreshGate;
+    /** One poll cycle. Exposed for tests. */
+    tick(): Promise<void>;
+    /** Test seam. */
+    __setModeForTest(mode: ShockWakeMode): void;
+}