@senpi/runtime 3.0.6-dev.skill-manager-v2.20260629194505 → 3.0.9-dev.20260710204324

package/dist/index.js

@@ -11,21 +11,10 @@
  *   that reason. Keeping every export in a single file (this one) avoids
  *   the loader's relative-import path entirely.
  */
-// dd-trace init MUST be the first executable statement in this file so it
-// patches Node core modules (http, fs, etc.) before any traceable resource is
-// constructed by the imports below. Gated on DD_TRACE_ENABLED=true so unit
-// tests and standalone CLI invocations do not pay the init cost.
-// `createRequire` is used because `dd-trace` is a CJS module and our
-// tsconfig uses Node16 modules — a top-level `import "dd-trace"` would
-// be hoisted above this gate by the bundler/loader.
-import { createRequire } from "node:module";
-const __require = createRequire(import.meta.url);
-if (process.env.DD_TRACE_ENABLED === "true") {
-    __require("dd-trace").init();
-}
 import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { SenpiClient } from "./senpi/client.js";
+import { AuditQueryError } from "./runtime/audit-query.types.js";
 import { buildRuntimeStateDir, archiveStateDir } from "./runtime/state-layout.js";
 import { registerSenpiCli } from "./cli/senpi-commands.js";
 import { readSenpiCliStore, resolveSenpiApiKeyFromStore, resolveSenpiBaseStateDir, resolveTelegramChatIdFromStore, } from "./cli/senpi-cli-config.js";
@@ -39,21 +28,28 @@ import { createScannerProvidersForRun } from "./runtime/create-scanner-providers
 import { initDsl } from "./dsl/index.js";
 import { initHealth } from "./health/index.js";
 import { initRisk } from "./risk/index.js";
+import { readRiskAuditEntries } from "./risk/risk-audit-log.js";
+import { readEvents } from "./telemetry/event-store.js";
 import { VERSION } from "./version.js";
 import { resolvePackageName } from "./runtime/auto-update/resolve-package-name.js";
 import { runOpenClawPluginsUpdate } from "./runtime/auto-update/run-update-command.js";
-import { BUS_EVENT_MAP } from "./tracking/constants.js";
-import { createPluginEventTracker } from "./tracking/plugin-event-tracker.js";
-import { createPluginSpanTracker, registerSpanHooks, setDefaultSpanTracker, } from "./tracking/spans/index.js";
+import { registerSpanHooks } from "./telemetry/spans/index.js";
+import { initDefaultPiiRedactor } from "./telemetry/spans/redact-pii.js";
+import { initOtelSdk, shutdownOtelSdk } from "./telemetry/otel-sdk.js";
 import { getLogLevel, getLogLevelSource, parseLogLevel, setErrorNotifier, setLogLevel, } from "./utils/logger.js";
 import { ExternalScannerIngestError, } from "./scanners/external-scanner-receiver.js";
 import { createLogger } from "./utils/logger.js";
+import { EVENT_NAME, eventAttrs } from "./utils/event-catalog.js";
+import { emitEvent } from "./actions/event-derivation.js";
+import { buildRuntimeCreatedEvent, buildRuntimeDeletedEvent } from "./runtime/lifecycle-events.js";
+import { isWalletAddress } from "./utils/wallet-address.js";
 import { fileURLToPath } from "node:url";
 import { loadApiConfig } from "./runtime-api/config.js";
 import { startApi } from "./runtime-api/lifecycle.js";
 import { ingestSignalsHandler } from "./runtime-api/handlers/ingest-signals.js";
 import { createIntakeContext } from "./runtime-api/intake/intake-context.js";
 import { wireRuntime, intakeUrlFor } from "./runtime-api/intake/intake-mount.js";
+import { ingestDispatchMutex, ingestDispatchKey } from "./runtime-api/intake/ingest-mutex.js";
 import { loadRuntimeConfig } from "./runtime/load-runtime-config.js";
 /** Initialize all core features (DSL, risk, health) on the given event bus. */
 export function initCore(bus) {
@@ -140,8 +136,11 @@ function formatSharedLoggerErrorNotification(payload) {
         `level: ${payload.level}`,
         `message: ${payload.message}`,
     ];
-    if (payload.meta !== undefined) {
-        lines.push(`meta:\n${stringifyForTelegram(payload.meta)}`);
+    if (payload.exception !== undefined) {
+        lines.push(`exception:\n${stringifyForTelegram(payload.exception)}`);
+    }
+    if (payload.attributes !== undefined) {
+        lines.push(`attributes:\n${stringifyForTelegram(payload.attributes)}`);
     }
     return trimTelegramMessage(lines.join("\n"));
 }
@@ -267,16 +266,27 @@ const senpiRuntimePlugin = {
         // mcpTransport = gateway-injected (no eager connect); apiKey = self-managed SenpiClient
         // (lazy connect — the R7 boot-resilience path). No secret is logged, only presence + url.
         pluginLogger.info(`[senpi-runtime] MCP transport: ${mcpTransport ? "mcpTransport (gateway-injected)" : "apiKey (self-managed SenpiClient)"}; mcpUrl=${process.env.SENPI_MCP_URL ?? "(default)"}`);
-        const pluginEventTracker = createPluginEventTracker(apiKey ?? process.env.SENPI_AUTH_TOKEN ?? process.env.SENPI_API_KEY);
-        // Span telemetry — one tracker per gateway, shared across all hosted runtimes
-        // and OpenClaw hook activity. Captures llm/tool/subagent/agent_end via
-        // OpenClaw plugin hooks; direct-SDK paths (AnthropicLlmDecision) emit
-        // through the same tracker via factory injection.
-        const pluginSpanTracker = createPluginSpanTracker(apiKey ?? process.env.SENPI_AUTH_TOKEN ?? process.env.SENPI_API_KEY);
-        setDefaultSpanTracker(pluginSpanTracker);
+        // Register the process-wide default PII redactor at boot (always on, no env gate)
+        // so `logger.event()` redact fields are scrubbed on the live path. Fire-and-forget;
+        // see initDefaultPiiRedactor in telemetry/spans/redact-pii.ts.
+        initDefaultPiiRedactor();
+        // OTel SDK stand-up at process scope. register() must stay synchronous (the gateway
+        // loader doesn't await it; awaiting init would defer the registrations below), so it's
+        // fire-and-forget — the hooks resolve their tracer lazily at fire time, by which point
+        // init has run. Self-guarding; see src/telemetry/otel-sdk.ts.
+        void initOtelSdk({
+            userToken: apiKey ?? process.env.SENPI_AUTH_TOKEN ?? process.env.SENPI_API_KEY,
+            serviceVersion: VERSION,
+        }).catch((err) => {
+            pluginLogger.warn("[senpi-runtime] OTel SDK init failed", {
+                err: err instanceof Error ? err.message : String(err),
+            });
+        });
+        // Agent telemetry — gateway hooks emit gen_ai spans (llm/tool/subagent) through
+        // the shared tracer; on-site MCP calls emit their own spans from SenpiClient.
         try {
-            registerSpanHooks({ api, tracker: pluginSpanTracker });
-            pluginLogger.info("[senpi-runtime] span hooks registered (9 hooks)");
+            registerSpanHooks({ api });
+            pluginLogger.info("[senpi-runtime] gen_ai span hooks registered (9 hooks)");
         }
         catch (err) {
             pluginLogger.warn("[senpi-runtime] failed to register span hooks", {
@@ -323,6 +333,24 @@ const senpiRuntimePlugin = {
         // PluginLogger surface (info/warn/error) lacks `debug`, while the
         // Logger contract used by `runtime-api/` includes it.
         const apiLogger = createLogger("[senpi-core][api]");
+        // A gateway seam failed to wire/launch a runtime's external scanner stack: the runtime is up but
+        // runs blind on internal scanners only. Two records, by design: a first-class `runtime.scanners_unwired`
+        // event (the queryable/alertable fact, by phase) and the migrated exception-form `logger.error`
+        // (carries the stack + trace context, and fans the error notifier so a blind runtime still pages).
+        const eventScannersUnwired = (phase, runtimeId, wallet, message, error) => {
+            apiLogger.event(EVENT_NAME.runtimeScannersUnwired, "error", {
+                body: message,
+                attributes: eventAttrs({
+                    "senpi.runtime.id": runtimeId,
+                    "senpi.strategy.address": wallet ? wallet.toLowerCase() : undefined,
+                    "senpi.scanners.launch_phase": phase,
+                }),
+            });
+            apiLogger.error(message, error, {
+                "senpi.runtime.id": runtimeId,
+                "senpi.scanners.launch_phase": phase,
+            });
+        };
         const lifecycleChatId = resolveTelegramChatIdFromStore(senpiCliStore);
         const lifecycleNotifications = lifecycleChatId
             ? createNotificationService({
@@ -459,8 +487,14 @@ const senpiRuntimePlugin = {
                         // Trace the sizing-relevant fields the narrowed request carries, so a
                         // field dropped at this seam is visible instead of vanishing silently.
                         apiLogger.debug(`[intake] ingest req signal_id=${signal.signal_id} scanner=${resolved.scannerName} asset=${signal.asset} direction=${signal.direction} marginPct=${signal.marginPct} leverage=${signal.leverage}`);
-                        void h
-                            .ingestExternalScannerData(request)
+                        // Serialize dispatch behind the shared per-key lock (engine guard
+                        // identity) so a same-scanner batch or overlapping POSTs ingest one
+                        // at a time instead of the engine rejecting all but the first as
+                        // UNAVAILABLE. Still void — the POST response never blocks on the
+                        // trade, just on lock ordering.
+                        const key = ingestDispatchKey(resolved.runtimeId, resolved.scannerName);
+                        void ingestDispatchMutex
+                            .withKeyLock(key, () => h.ingestExternalScannerData(request))
                             .then(() => {
                             apiLogger.info(`[intake] ingest ok signal_id=${signal.signal_id} scanner=${resolved.scannerName} asset=${signal.asset} scanner_id=${scannerId}`);
                         })
@@ -523,8 +557,8 @@ const senpiRuntimePlugin = {
                             }
                             catch (mountErr) {
                                 // Mount failure is non-fatal: the runtime itself is already up.
-                                // Log and skip the launcher for this runtime.
-                                apiLogger.error("[senpi-runtime] scanner mount failed — runtime running without supervised scanners", { runtimeId: entry.id, err: mountErr });
+                                // Event it and skip the launcher for this runtime.
+                                eventScannersUnwired("mount", entry.id, entry.wallet, "[senpi-runtime] scanner mount failed — runtime running without supervised scanners", mountErr);
                             }
                         }
                     }
@@ -603,7 +637,7 @@ const senpiRuntimePlugin = {
                         catch (startErr) {
                             await launcher.stop().catch(() => { });
                             launchers.delete(id);
-                            apiLogger.error("[senpi-runtime] supervised scanner launch failed — runtime running without it", { err: startErr });
+                            eventScannersUnwired("launch", id, runtimeHandles.get(id)?.wallet, "[senpi-runtime] supervised scanner launch failed — runtime running without it", startErr);
                         }
                     }
                 }
@@ -649,13 +683,11 @@ const senpiRuntimePlugin = {
                     runtimeHandles.delete(ids[i]);
                 }
                 pluginLogger.info("[senpi-runtime] All runtimes stopped");
-                // Flush plugin-scoped telemetry (lifecycle.runtime.created/deleted); otherwise
-                // BatchingTransport may still hold buffered events until the interval fires.
-                await pluginEventTracker.shutdown().catch((err) => {
-                    pluginLogger.warn("[senpi-runtime] plugin telemetry shutdown failed", {
-                        err: err instanceof Error ? err.message : String(err),
-                    });
-                });
+                // Final, process-global OTel SDK flush. Last step, after every runtime is
+                // stopped and all spans are emitted: we disabled HyperDX's own SIGTERM
+                // flush (stopOnTerminationSignals: false), so this is the only drain of the
+                // SDK's span/log buffers on exit.
+                await shutdownOtelSdk();
             },
         });
         pluginLogger.info("[senpi-runtime] calling api.registerCli(..., { commands: ['senpi'] })");
@@ -818,21 +850,6 @@ const senpiRuntimePlugin = {
             }
             registry.runtimes.push(entry);
             await writeRegistry(baseStateDir, registry);
-            const createdMapping = BUS_EVENT_MAP["tracking.runtime_created"];
-            pluginEventTracker.capture({
-                eventType: createdMapping.eventType,
-                category: createdMapping.category,
-                address: wallet,
-                data: {
-                    id: resolvedId,
-                    name: runtimeName,
-                    wallet,
-                    schemaVersion: parsedSchemaVersion,
-                    source: hasPath ? "file" : "inline",
-                    config: entry,
-                    timestamp: new Date().toISOString(),
-                },
-            });
             try {
                 const scannerProviders = await createScannerProvidersForRun({
                     mcpTransport,
@@ -848,6 +865,9 @@ const senpiRuntimePlugin = {
                     runtimeId: resolvedId,
                 });
                 runtimeHandles.set(resolvedId, handle);
+                // Registry create fact — distinct from the runtime.started boot transition (which also fires
+                // on a transient restart). Emitted inside emitEvent's guard so telemetry never fails the install.
+                emitEvent(apiLogger, () => buildRuntimeCreatedEvent({ runtimeId: resolvedId, address: wallet, recipeName: runtimeName }));
                 // ── hot-install supervised scanner wire ───────────────────────────────
                 // Live-install path: used when a runtime is registered after boot via
                 // senpi.installRuntime, while the API is already listening — the
@@ -888,13 +908,13 @@ const senpiRuntimePlugin = {
                             }
                             catch (startErr) {
                                 await hotLauncher.stop().catch(() => { });
-                                apiLogger.error("[senpi-runtime] hot-install supervised scanner launch failed — runtime running without it", { runtimeId: resolvedId, err: startErr });
+                                eventScannersUnwired("install_launch", resolvedId, wallet, "[senpi-runtime] hot-install supervised scanner launch failed — runtime running without it", startErr);
                             }
                         }
                     }
                     catch (wireErr) {
                         // Wire failure must NOT fail the install — the runtime is already up.
-                        apiLogger.error("[senpi-runtime] hot-install wiring failed — runtime running without supervised scanners", { runtimeId: resolvedId, err: wireErr });
+                        eventScannersUnwired("install_wire", resolvedId, wallet, "[senpi-runtime] hot-install wiring failed — runtime running without supervised scanners", wireErr);
                     }
                 }
                 // ──────────────────────────────────────────────────────────────────────
@@ -954,13 +974,8 @@ const senpiRuntimePlugin = {
                 });
                 return;
             }
-            const targetWallet = deletedEntry?.wallet ??
-                handle?.wallet ??
-                (typeof targetAddress === "string" ? targetAddress : "");
-            let openPositionsAbandoned = 0;
-            let archivePath;
             if (handle) {
-                openPositionsAbandoned = await handle.teardownDslForRuntimeDeletion();
+                await handle.teardownDslForRuntimeDeletion();
                 await handle.stop();
                 runtimeHandles.delete(targetId);
             }
@@ -977,32 +992,25 @@ const senpiRuntimePlugin = {
                 const runtimeStateDir = buildRuntimeStateDir(baseStateDir, targetId, deletedEntry.wallet ?? "");
                 const archivesDir = join(baseStateDir, "archives");
                 try {
-                    archivePath = await archiveStateDir(runtimeStateDir, archivesDir, targetId, deletedEntry.wallet ?? "");
+                    const archivePath = await archiveStateDir(runtimeStateDir, archivesDir, targetId, deletedEntry.wallet ?? "");
                     api.logger.info(`[senpi-runtime] Archived state to ${archivePath}`);
                 }
                 catch (err) {
                     api.logger.warn("[senpi-runtime] Failed to archive state dir", { err });
                 }
             }
-            const deletedMapping = BUS_EVENT_MAP["tracking.runtime_deleted"];
-            pluginEventTracker.capture({
-                eventType: deletedMapping.eventType,
-                category: deletedMapping.category,
-                address: targetWallet,
-                data: {
-                    id: targetId,
-                    wallet: targetWallet,
-                    schemaVersion: deletedEntry?.schemaVersion,
-                    reason: "user_initiated",
-                    openPositionsAbandoned,
-                    ...(typeof archivePath === "string" ? { archivedAt: archivePath } : {}),
-                    timestamp: new Date().toISOString(),
-                },
-            });
             if (deletedEntry) {
                 const next = registry.runtimes.filter((e) => e.id !== targetId);
                 await writeRegistry(baseStateDir, { ...registry, runtimes: next });
             }
+            // Registry delete fact — the permanent-removal discriminator a transient runtime.stopped can't
+            // give. Unconditional (a never-booted runtime stops no handle, so emits no runtime.stopped) and
+            // inside emitEvent's guard so telemetry never fails the delete.
+            emitEvent(apiLogger, () => buildRuntimeDeletedEvent({
+                runtimeId: targetId,
+                address: deletedEntry?.wallet,
+                hadLiveHandle: Boolean(handle),
+            }));
             respond(true, { id: targetId });
         }, { scope: "operator.write" });
         /**
@@ -1225,7 +1233,9 @@ const senpiRuntimePlugin = {
                 try {
                     const state = await handle.getSystemState();
                     respond(true, {
-                        state: state ? { ...state, runtimeId } : null,
+                        state: state
+                            ? enrichScannerLiveness({ ...state, runtimeId }, sharedIntakeContext)
+                            : null,
                         updater,
                     });
                 }
@@ -1238,7 +1248,7 @@ const senpiRuntimePlugin = {
                 }
                 return;
             }
-            const states = await collectRuntimeSystemStates(runtimeHandles, api.logger, baseStateDir);
+            const states = (await collectRuntimeSystemStates(runtimeHandles, api.logger, baseStateDir)).map((s) => enrichScannerLiveness(s, sharedIntakeContext));
             respond(true, { states, updater });
         }, { scope: "operator.read" });
         /**
@@ -1391,6 +1401,157 @@ const senpiRuntimePlugin = {
                 });
             }
         }, { scope: "operator.read" });
+        // Backend trade-audit trail (MCP tool calls + AI reasoning), already
+        // reachable on HTTP `/audit`. Passes through the caller-controlled subset
+        // of the audit_query contract; resource scoping (wallet → strategyId) is
+        // owned by handle.auditQuery, never the caller.
+        api.registerGatewayMethod("senpi.auditQuery", async (ctx) => {
+            const respond = ctx.respond;
+            const runtimeId = typeof ctx.params?.runtimeId === "string" ? ctx.params.runtimeId : undefined;
+            if (!runtimeId) {
+                respond(false, undefined, { code: "INVALID_REQUEST", message: "runtimeId is required" });
+                return;
+            }
+            const handle = getRuntimeHandleOrRespond(runtimeHandles, runtimeId, respond);
+            if (!handle) {
+                return;
+            }
+            const p = ctx.params ?? {};
+            const args = {};
+            if (typeof p.tool_name === "string")
+                args.tool_name = p.tool_name;
+            if (p.action_type === "read" || p.action_type === "create" || p.action_type === "update" || p.action_type === "delete") {
+                args.action_type = p.action_type;
+            }
+            if (typeof p.success === "boolean")
+                args.success = p.success;
+            if (typeof p.start_time === "string")
+                args.start_time = p.start_time;
+            if (typeof p.end_time === "string")
+                args.end_time = p.end_time;
+            if (typeof p.limit === "number")
+                args.limit = p.limit;
+            if (typeof p.offset === "number")
+                args.offset = p.offset;
+            try {
+                const result = await handle.auditQuery(args);
+                respond(true, { result, strategyId: handle.getStrategyId() });
+            }
+            catch (err) {
+                if (err instanceof AuditQueryError) {
+                    respond(false, undefined, { code: err.code, message: err.message });
+                    return;
+                }
+                api.logger.warn("[senpi-runtime] auditQuery error", { runtimeId, err });
+                respond(false, undefined, {
+                    code: "INTERNAL_ERROR",
+                    message: `Failed to query audit trail: ${formatGatewayError(err)}`,
+                });
+            }
+        }, { scope: "operator.read" });
+        // Per-wallet risk gate-check audit log (on-disk JSONL). The Runtime keeps
+        // its state root private, so re-derive it from baseStateDir + the handle's
+        // wallet (same helper the writer's stateDir was built with); the writer
+        // nests entries under `<root>/<address>/risk-guard/audit.jsonl`.
+        api.registerGatewayMethod("senpi.getRiskAudit", async (ctx) => {
+            const respond = ctx.respond;
+            const runtimeId = typeof ctx.params?.runtimeId === "string" ? ctx.params.runtimeId : undefined;
+            if (!runtimeId) {
+                respond(false, undefined, { code: "INVALID_REQUEST", message: "runtimeId is required" });
+                return;
+            }
+            const handle = getRuntimeHandleOrRespond(runtimeHandles, runtimeId, respond);
+            if (!handle) {
+                return;
+            }
+            const resolvedAddress = typeof ctx.params?.address === "string" && ctx.params.address.length > 0
+                ? ctx.params.address
+                : handle.wallet;
+            if (!resolvedAddress) {
+                respond(false, undefined, {
+                    code: "INVALID_REQUEST",
+                    message: "address is required when the runtime wallet is unknown",
+                });
+                return;
+            }
+            // Path safety: the address builds the on-disk audit path; reject a non-wallet before the read.
+            if (!isWalletAddress(resolvedAddress)) {
+                respond(false, undefined, { code: "INVALID_REQUEST", message: "address is not a valid wallet" });
+                return;
+            }
+            const limit = typeof ctx.params?.limit === "number" && ctx.params.limit > 0 ? ctx.params.limit : 100;
+            const stateDir = buildRuntimeStateDir(baseStateDir, runtimeId, handle.wallet ?? "");
+            try {
+                const entries = await readRiskAuditEntries(stateDir, resolvedAddress, limit);
+                respond(true, { entries, address: resolvedAddress });
+            }
+            catch (err) {
+                api.logger.warn("[senpi-runtime] getRiskAudit error", { runtimeId, err });
+                respond(false, undefined, {
+                    code: "INTERNAL_ERROR",
+                    message: `Failed to read risk audit: ${formatGatewayError(err)}`,
+                });
+            }
+        }, { scope: "operator.read" });
+        // Per-strategy local domain-event ring (on-disk JSONL) — the trade narrative, queryable locally.
+        // Same state-root re-derivation as getRiskAudit: the Runtime keeps its root private, so rebuild it
+        // from baseStateDir + the handle's wallet; the writer nests rows under `<root>/strategies/<address>/events/`.
+        api.registerGatewayMethod("senpi.getEvents", async (ctx) => {
+            const respond = ctx.respond;
+            const runtimeId = typeof ctx.params?.runtimeId === "string" ? ctx.params.runtimeId : undefined;
+            if (!runtimeId) {
+                respond(false, undefined, { code: "INVALID_REQUEST", message: "runtimeId is required" });
+                return;
+            }
+            const handle = getRuntimeHandleOrRespond(runtimeHandles, runtimeId, respond);
+            if (!handle) {
+                return;
+            }
+            const p = ctx.params ?? {};
+            const resolvedAddress = typeof p.address === "string" && p.address.length > 0 ? p.address : handle.wallet;
+            if (!resolvedAddress) {
+                respond(false, undefined, {
+                    code: "INVALID_REQUEST",
+                    message: "address is required when the runtime wallet is unknown",
+                });
+                return;
+            }
+            // Path safety: the address builds the on-disk events path; reject a non-wallet before the read.
+            if (!isWalletAddress(resolvedAddress)) {
+                respond(false, undefined, { code: "INVALID_REQUEST", message: "address is not a valid wallet" });
+                return;
+            }
+            const query = {};
+            if (typeof p.name === "string")
+                query.name = p.name;
+            if (typeof p.asset === "string")
+                query.asset = p.asset;
+            if (p.level === "debug" || p.level === "info" || p.level === "warn" || p.level === "error") {
+                query.level = p.level;
+            }
+            // ISO 8601 (or epoch-ms) time bounds → epoch ms; Date.parse returns NaN (not undefined) on
+            // unparseable input, so Number.isFinite is the carry — no separate undefined check needed.
+            const sinceMs = typeof p.since === "string" ? Date.parse(p.since) : NaN;
+            if (Number.isFinite(sinceMs))
+                query.sinceMs = sinceMs;
+            const untilMs = typeof p.until === "string" ? Date.parse(p.until) : NaN;
+            if (Number.isFinite(untilMs))
+                query.untilMs = untilMs;
+            if (typeof p.limit === "number" && p.limit > 0)
+                query.limit = p.limit;
+            const stateDir = buildRuntimeStateDir(baseStateDir, runtimeId, handle.wallet ?? "");
+            try {
+                const entries = await readEvents(stateDir, resolvedAddress, query);
+                respond(true, { entries, address: resolvedAddress });
+            }
+            catch (err) {
+                api.logger.warn("[senpi-runtime] getEvents error", { runtimeId, err });
+                respond(false, undefined, {
+                    code: "INTERNAL_ERROR",
+                    message: `Failed to read events: ${formatGatewayError(err)}`,
+                });
+            }
+        }, { scope: "operator.read" });
         // ─── Skills manager — read + mutate ──────────────────────────────────────
         api.registerGatewayMethod("senpi.skills.status", async (ctx) => {
             const respond = ctx.respond;
@@ -1505,6 +1666,30 @@ async function collectRuntimeHealthStatuses(runtimeHandles, logger) {
         }
     }))).filter((status) => status !== null);
 }
+/**
+ * Stamps external-scanner `lastAliveAt` onto the scanners component from the shared intake
+ * liveness clock. Liveness is keyed by the ephemeral scanner_id; the registry resolves it back
+ * to the stable scanner name (which matches the system-state row's scannerId). Interval/internal
+ * scanners never POST, so they keep the module's `null`. Mutates the freshly-built rows in place.
+ */
+function enrichScannerLiveness(state, intake) {
+    const rows = state.components?.scanners?.state?.scanners;
+    if (!intake || !Array.isArray(rows) || rows.length === 0) {
+        return state;
+    }
+    const liveByName = new Map();
+    for (const entry of intake.registry.entries()) {
+        if (entry.runtimeId === state.runtimeId) {
+            liveByName.set(entry.scannerName, intake.liveness.lastAliveAt(entry.scannerId));
+        }
+    }
+    for (const row of rows) {
+        if (row.scheduleMode === "external") {
+            row.lastAliveAt = liveByName.get(row.scannerId) ?? null;
+        }
+    }
+    return state;
+}
 async function collectRuntimeSystemStates(runtimeHandles, logger, baseStateDir) {
     return (await Promise.all(Array.from(runtimeHandles, async ([runtimeId, handle]) => {
         try {