@tloncorp/openclaw 0.4.3 → 0.6.1

package/dist/index.js

@@ -1,59 +1,54 @@
-import { gatewayStop } from "@tloncorp/api";
-import { spawn } from "node:child_process";
-import { readFileSync } from "node:fs";
-import { createRequire } from "node:module";
-import { dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";
-import { tlonPlugin } from "./src/channel.js";
-import { createGatewayStatusManager, setGatewayStatusManager } from "./src/gateway-status.js";
-import { resolveBridgeForCommand } from "./src/monitor/command-auth.js";
-import { handleOwnerListenCommand } from "./src/owner-listen-command.js";
-import { setTlonRuntime } from "./src/runtime.js";
-import { getSessionRole } from "./src/session-roles.js";
-import { recordToolCall } from "./src/telemetry.js";
-import { resolveTlonBinary } from "./src/tlon-binary.js";
-import { checkBlockedSendOperation } from "./src/tlon-tool-guard.js";
-import { formatToolTraceEvent, liveToolTraceContentsEnabled, shouldLogAfterToolTrace, } from "./src/tool-trace.js";
-import { resolveTlonAccount, listTlonAccountIds } from "./src/types.js";
-export { tlonPlugin } from "./src/channel.js";
-export { setTlonRuntime } from "./src/runtime.js";
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { defineChannelPluginEntry, } from 'openclaw/plugin-sdk/core';
+import { onDiagnosticEvent, onInternalDiagnosticEvent, } from 'openclaw/plugin-sdk/diagnostic-runtime';
+import { tlonPlugin } from './src/channel.js';
+import { installTlonDiagnosticSubscriptions, shouldInstallTlonDiagnosticSubscriptions, } from './src/diagnostic-subscriptions.js';
+import { sendGatewayStop } from './src/gateway-status.js';
+import { createGatewayStatusManager, setGatewayStatusManager, } from './src/gateway-status.js';
+import { resolveBridgeForCommand } from './src/monitor/command-auth.js';
+import { isRouteDebugEnabled } from './src/monitor/session-routing.js';
+import { handleOwnerListenCommand } from './src/owner-listen-command.js';
+import { setTlonRuntime } from './src/runtime.js';
+import { getSessionRole } from './src/session-roles.js';
+import { parseTlonTarget } from './src/targets.js';
+import { formatTlonTelemetryErrorText, recordToolCall, reportHarnessError, reportOutboundRoute, reportPluginError, reportSessionDiagnostic, reportSessionLifecycle, reportSessionTurnCreated, reportTelemetryError, } from './src/telemetry.js';
+import { resolveTlonBinary } from './src/tlon-binary.js';
+import { checkBlockedSendOperation } from './src/tlon-tool-guard.js';
+import { formatToolTraceEvent, liveToolTraceContentsEnabled, shouldLogAfterToolTrace, } from './src/tool-trace.js';
+import { listTlonAccountIds, resolveTlonAccount } from './src/types.js';
+import { formatTlonVersionIdentity, resolveTlonSkillVersion, setTlonSkillVersionResolver, } from './src/version.js';
+export { tlonPlugin } from './src/channel.js';
+export { setTlonRuntime } from './src/runtime.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const require = createRequire(import.meta.url);
-function readPluginVersion() {
-    try {
-        const { version } = require("./package.json");
-        return version;
-    }
-    catch {
-        try {
-            const raw = readFileSync(new URL("./package.json", import.meta.url), "utf-8");
-            return JSON.parse(raw).version;
-        }
-        catch {
-            return "unknown";
-        }
-    }
-}
 // Whitelist of allowed tlon subcommands
 const ALLOWED_TLON_COMMANDS = new Set([
-    "activity",
-    "channels",
-    "contacts",
-    "dms",
-    "expose",
-    "groups",
-    "hooks",
-    "messages",
-    "notebook",
-    "posts",
-    "settings",
-    "upload",
-    "help",
-    "version",
+    'activity',
+    'channels',
+    'contacts',
+    'dms',
+    'expose',
+    'groups',
+    'hooks',
+    'messages',
+    'notebook',
+    'posts',
+    'settings',
+    'upload',
+    'help',
+    'version',
 ]);
 /** Credential flags that the tlon skill binary accepts before the subcommand. */
-const CREDENTIAL_FLAGS_WITH_VALUE = new Set(["--config", "--url", "--ship", "--code", "--cookie"]);
+const CREDENTIAL_FLAGS_WITH_VALUE = new Set([
+    '--config',
+    '--url',
+    '--ship',
+    '--code',
+    '--cookie',
+]);
 /**
  * Find the first positional argument (subcommand) by skipping credential flags
  * and their values. Returns the index into `args`, or -1 if none found.
@@ -63,8 +58,8 @@ function findSubcommandIndex(args) {
     while (i < args.length) {
         const arg = args[i];
         // --flag=value form: skip one token
-        if (arg.startsWith("--") && arg.includes("=")) {
-            const flag = arg.slice(0, arg.indexOf("="));
+        if (arg.startsWith('--') && arg.includes('=')) {
+            const flag = arg.slice(0, arg.indexOf('='));
             if (CREDENTIAL_FLAGS_WITH_VALUE.has(flag)) {
                 i += 1;
                 continue;
@@ -85,7 +80,7 @@ function findSubcommandIndex(args) {
  */
 function shellSplit(str) {
     const args = [];
-    let cur = "";
+    let cur = '';
     let inDouble = false;
     let inSingle = false;
     let escape = false;
@@ -95,7 +90,7 @@ function shellSplit(str) {
             escape = false;
             continue;
         }
-        if (ch === "\\" && !inSingle) {
+        if (ch === '\\' && !inSingle) {
             escape = true;
             continue;
         }
@@ -110,7 +105,7 @@ function shellSplit(str) {
         if (/\s/.test(ch) && !inDouble && !inSingle) {
             if (cur) {
                 args.push(cur);
-                cur = "";
+                cur = '';
             }
             continue;
         }
@@ -124,7 +119,7 @@ function shellSplit(str) {
 /**
  * Run the tlon command and return the result
  */
-function runTlonCommand(binary, args, credentials) {
+function runTlonCommand(binary, args, credentials, options) {
     return new Promise((resolve, reject) => {
         const env = { ...process.env };
         if (credentials) {
@@ -133,19 +128,39 @@ function runTlonCommand(binary, args, credentials) {
             env.URBIT_CODE = credentials.code;
         }
         const child = spawn(binary, args, { env });
-        let stdout = "";
-        let stderr = "";
-        child.stdout.on("data", (data) => {
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        let timeout;
+        const timeoutMs = options?.timeoutMs;
+        const cleanup = () => {
+            if (timeout) {
+                clearTimeout(timeout);
+                timeout = undefined;
+            }
+        };
+        child.stdout.on('data', (data) => {
             stdout += data.toString();
         });
-        child.stderr.on("data", (data) => {
+        child.stderr.on('data', (data) => {
             stderr += data.toString();
         });
-        child.on("error", (err) => {
+        child.on('error', (err) => {
+            cleanup();
             reject(new Error(`Failed to run tlon: ${err.message}`));
         });
-        child.on("close", (code) => {
-            if (code !== 0) {
+        if (timeoutMs) {
+            timeout = setTimeout(() => {
+                timedOut = true;
+                child.kill('SIGTERM');
+            }, timeoutMs);
+        }
+        child.on('close', (code) => {
+            cleanup();
+            if (timedOut) {
+                reject(new Error(`tlon timed out after ${timeoutMs}ms`));
+            }
+            else if (code !== 0) {
                 reject(new Error(stderr || `tlon exited with code ${code}`));
             }
             else {
@@ -154,29 +169,388 @@ function runTlonCommand(binary, args, credentials) {
         });
     });
 }
+function firstLine(value) {
+    return value.trim().split(/\r?\n/)[0]?.trim() || 'unknown';
+}
+function summarizeError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return firstLine(message).slice(0, 180);
+}
+async function readTlonSkillVersion(binary) {
+    try {
+        return firstLine(await runTlonCommand(binary, ['--version'], undefined, {
+            timeoutMs: 5_000,
+        }));
+    }
+    catch (error) {
+        return `unavailable (${summarizeError(error)})`;
+    }
+}
+function isTlonSessionDiagnosticEvent(event) {
+    return (event.type === 'session.stalled' ||
+        event.type === 'session.stuck' ||
+        event.type === 'session.recovery.requested' ||
+        event.type === 'session.recovery.completed');
+}
+function stringField(event, key) {
+    const value = event[key];
+    return typeof value === 'string' && value.trim() ? value : null;
+}
+function numberField(event, key) {
+    const value = event[key];
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+function diagnosticErrorText(event) {
+    return stringField(event, 'error') ?? stringField(event, 'message');
+}
+function stringListField(event, key) {
+    const value = event[key];
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .map((entry) => (typeof entry === 'string' ? entry.trim() : ''))
+        .filter(Boolean);
+}
+function diagnosticSummary(parts) {
+    return parts
+        .filter(([, value]) => value !== null && value !== undefined && value !== '')
+        .map(([key, value]) => `${key}=${String(value)}`)
+        .join(' ');
+}
+function reportHarnessDiagnostic(event) {
+    const type = stringField(event, 'type');
+    if (!type) {
+        return;
+    }
+    if (type === 'session.turn.created') {
+        reportSessionTurnCreated({
+            type,
+            sessionKey: stringField(event, 'sessionKey'),
+            sessionId: stringField(event, 'sessionId'),
+            runId: stringField(event, 'runId'),
+            agentId: stringField(event, 'agentId'),
+        });
+        return;
+    }
+    const common = {
+        harnessEventType: type,
+        sessionKey: stringField(event, 'sessionKey'),
+        sessionId: stringField(event, 'sessionId'),
+        runId: stringField(event, 'runId'),
+        agentId: stringField(event, 'agentId'),
+        provider: stringField(event, 'provider'),
+        model: stringField(event, 'model'),
+        phase: stringField(event, 'phase'),
+        outcome: stringField(event, 'outcome'),
+        errorCategory: stringField(event, 'errorCategory'),
+        failureKind: stringField(event, 'failureKind'),
+        durationMs: numberField(event, 'durationMs'),
+        errorText: diagnosticErrorText(event),
+    };
+    switch (type) {
+        case 'harness.run.error':
+            reportHarnessError({
+                ...common,
+                errorScope: 'harness',
+            });
+            return;
+        case 'harness.run.completed':
+            if (common.outcome === 'completed') {
+                return;
+            }
+            reportHarnessError({
+                ...common,
+                errorScope: 'harness',
+            });
+            return;
+        case 'model.call.error':
+            reportHarnessError({
+                ...common,
+                errorScope: 'model',
+            });
+            return;
+        case 'model.failover': {
+            const reason = stringField(event, 'reason');
+            const fromProvider = stringField(event, 'fromProvider');
+            const fromModel = stringField(event, 'fromModel');
+            const toProvider = stringField(event, 'toProvider');
+            const toModel = stringField(event, 'toModel');
+            reportHarnessError({
+                ...common,
+                errorScope: 'model',
+                provider: fromProvider,
+                model: fromModel,
+                phase: stringField(event, 'lane'),
+                outcome: 'failover',
+                errorCategory: 'model_failover',
+                failureKind: reason,
+                errorText: diagnosticSummary([
+                    ['fromProvider', fromProvider],
+                    ['fromModel', fromModel],
+                    ['toProvider', toProvider],
+                    ['toModel', toModel],
+                    ['reason', reason],
+                    ['cascadeDepth', numberField(event, 'cascadeDepth')],
+                ]),
+            });
+            return;
+        }
+        case 'tool.execution.error':
+            reportHarnessError({
+                ...common,
+                errorScope: 'tool',
+                toolName: stringField(event, 'toolName'),
+            });
+            return;
+        case 'tool.execution.blocked': {
+            const deniedReason = stringField(event, 'deniedReason');
+            const reason = stringField(event, 'reason');
+            reportHarnessError({
+                ...common,
+                errorScope: 'tool',
+                toolName: stringField(event, 'toolName'),
+                phase: stringField(event, 'toolSource'),
+                outcome: 'blocked',
+                errorCategory: 'tool_blocked',
+                failureKind: deniedReason,
+                errorText: reason ?? deniedReason,
+            });
+            return;
+        }
+        case 'tool.loop': {
+            const level = stringField(event, 'level');
+            const action = stringField(event, 'action');
+            if (level !== 'critical' && action !== 'block') {
+                return;
+            }
+            reportHarnessError({
+                ...common,
+                errorScope: 'tool',
+                toolName: stringField(event, 'toolName'),
+                phase: level,
+                outcome: action,
+                errorCategory: 'tool_loop',
+                failureKind: stringField(event, 'detector'),
+                errorText: stringField(event, 'message') ??
+                    diagnosticSummary([
+                        ['level', level],
+                        ['action', action],
+                        ['detector', stringField(event, 'detector')],
+                        ['count', numberField(event, 'count')],
+                    ]),
+            });
+            return;
+        }
+        case 'run.completed':
+            if (common.outcome === 'completed') {
+                return;
+            }
+            reportHarnessError({
+                ...common,
+                errorScope: 'run',
+            });
+            return;
+        case 'message.delivery.error':
+            reportHarnessError({
+                ...common,
+                errorScope: 'message_delivery',
+                phase: stringField(event, 'deliveryKind'),
+            });
+            return;
+        case 'message.dispatch.completed':
+            if (common.outcome !== 'error') {
+                return;
+            }
+            reportHarnessError({
+                ...common,
+                errorScope: 'message_dispatch',
+                phase: stringField(event, 'source'),
+            });
+            return;
+        case 'message.processed':
+            if (common.outcome !== 'error') {
+                return;
+            }
+            reportHarnessError({
+                ...common,
+                errorScope: 'message_processing',
+                phase: stringField(event, 'channel'),
+            });
+            return;
+        case 'diagnostic.async_queue.dropped':
+            reportHarnessError({
+                ...common,
+                errorScope: 'diagnostics',
+                outcome: 'dropped',
+                errorCategory: 'diagnostic_async_queue_dropped',
+                failureKind: 'queue_full',
+                errorText: diagnosticSummary([
+                    ['droppedEvents', numberField(event, 'droppedEvents')],
+                    ['droppedTrustedEvents', numberField(event, 'droppedTrustedEvents')],
+                    [
+                        'droppedUntrustedEvents',
+                        numberField(event, 'droppedUntrustedEvents'),
+                    ],
+                    ['queueLength', numberField(event, 'queueLength')],
+                    ['maxQueueLength', numberField(event, 'maxQueueLength')],
+                ]),
+            });
+            return;
+        case 'diagnostic.liveness.warning': {
+            const reasons = stringListField(event, 'reasons');
+            reportHarnessError({
+                ...common,
+                errorScope: 'runtime',
+                phase: stringField(event, 'phase'),
+                outcome: 'warning',
+                errorCategory: 'liveness_warning',
+                failureKind: reasons.join(',') || null,
+                durationMs: numberField(event, 'intervalMs'),
+                errorText: diagnosticSummary([
+                    ['reasons', reasons.join(',')],
+                    ['eventLoopDelayP99Ms', numberField(event, 'eventLoopDelayP99Ms')],
+                    ['eventLoopDelayMaxMs', numberField(event, 'eventLoopDelayMaxMs')],
+                    ['cpuCoreRatio', numberField(event, 'cpuCoreRatio')],
+                    ['active', numberField(event, 'active')],
+                    ['waiting', numberField(event, 'waiting')],
+                    ['queued', numberField(event, 'queued')],
+                ]),
+            });
+            return;
+        }
+        case 'diagnostic.memory.pressure': {
+            const memory = event.memory;
+            const memoryNumber = (key) => {
+                const value = memory?.[key];
+                return typeof value === 'number' && Number.isFinite(value)
+                    ? value
+                    : null;
+            };
+            reportHarnessError({
+                ...common,
+                errorScope: 'runtime',
+                outcome: stringField(event, 'level'),
+                errorCategory: 'memory_pressure',
+                failureKind: stringField(event, 'reason'),
+                durationMs: numberField(event, 'windowMs'),
+                errorText: diagnosticSummary([
+                    ['level', stringField(event, 'level')],
+                    ['reason', stringField(event, 'reason')],
+                    ['rssBytes', memoryNumber('rssBytes')],
+                    ['heapUsedBytes', memoryNumber('heapUsedBytes')],
+                    ['thresholdBytes', numberField(event, 'thresholdBytes')],
+                    ['rssGrowthBytes', numberField(event, 'rssGrowthBytes')],
+                ]),
+            });
+            return;
+        }
+        case 'payload.large':
+            if (stringField(event, 'action') !== 'rejected') {
+                return;
+            }
+            reportHarnessError({
+                ...common,
+                errorScope: 'payload',
+                phase: stringField(event, 'surface'),
+                outcome: 'rejected',
+                errorCategory: 'payload_large',
+                failureKind: stringField(event, 'reason'),
+                errorText: diagnosticSummary([
+                    ['surface', stringField(event, 'surface')],
+                    ['channel', stringField(event, 'channel')],
+                    ['pluginId', stringField(event, 'pluginId')],
+                    ['bytes', numberField(event, 'bytes')],
+                    ['limitBytes', numberField(event, 'limitBytes')],
+                    ['count', numberField(event, 'count')],
+                    ['reason', stringField(event, 'reason')],
+                ]),
+            });
+            return;
+    }
+}
+function safeTelemetryObserver(params) {
+    try {
+        params.run();
+    }
+    catch (error) {
+        params.logger.warn(`[tlon] Telemetry observer failed (${params.telemetrySource}${params.sourceEventName ? `:${params.sourceEventName}` : ''}): ${String(error)}`);
+        try {
+            reportTelemetryError({
+                telemetrySource: params.telemetrySource,
+                sourceEventName: params.sourceEventName,
+                sessionKey: params.sessionKey,
+                sessionId: params.sessionId,
+                runId: params.runId,
+                agentId: params.agentId,
+                errorKind: error instanceof Error ? error.name : typeof error,
+                errorText: formatTlonTelemetryErrorText(error),
+            });
+        }
+        catch (reportError) {
+            params.logger.warn(`[tlon] Telemetry error reporting failed: ${String(reportError)}`);
+        }
+    }
+}
+function installTelemetryDiagnosticObservers(api) {
+    return installTlonDiagnosticSubscriptions(() => {
+        const unsubscribeDiagnosticEvents = onDiagnosticEvent((event) => {
+            const candidate = event;
+            safeTelemetryObserver({
+                logger: api.logger,
+                telemetrySource: 'diagnostic_session',
+                sourceEventName: candidate.type,
+                sessionKey: candidate.sessionKey,
+                sessionId: candidate.sessionId,
+                run: () => {
+                    if (isTlonSessionDiagnosticEvent(candidate)) {
+                        reportSessionDiagnostic(candidate);
+                    }
+                },
+            });
+        });
+        const unsubscribeInternalDiagnosticEvents = onInternalDiagnosticEvent((event) => {
+            const candidate = event;
+            safeTelemetryObserver({
+                logger: api.logger,
+                telemetrySource: 'diagnostic_internal',
+                sourceEventName: stringField(candidate, 'type'),
+                sessionKey: stringField(candidate, 'sessionKey'),
+                sessionId: stringField(candidate, 'sessionId'),
+                runId: stringField(candidate, 'runId'),
+                agentId: stringField(candidate, 'agentId'),
+                run: () => reportHarnessDiagnostic(candidate),
+            });
+        });
+        return () => {
+            unsubscribeDiagnosticEvents();
+            unsubscribeInternalDiagnosticEvents();
+        };
+    });
+}
 export default defineChannelPluginEntry({
-    id: "tlon",
-    name: "Tlon",
-    description: "Tlon/Urbit channel plugin",
+    id: 'tlon',
+    name: 'Tlon',
+    description: 'Tlon/Urbit channel plugin',
     plugin: tlonPlugin,
     setRuntime: setTlonRuntime,
     registerFull(api) {
-        // Import version info lazily
-        const PLUGIN_VERSION = readPluginVersion();
-        let PLUGIN_COMMIT = "unknown";
-        try {
-            PLUGIN_COMMIT = require("./src/version.generated.js")
-                .PLUGIN_COMMIT;
-        }
-        catch {
-            // version.generated.js may not exist in all environments
-        }
         // ── Gateway-status liveness integration ───────────────────
         //
         // v1 requires exactly one Tlon account. With multiple accounts, multiple
-        // monitors call configureTlonApiWithPoke() and the last one wins the global
-        // @tloncorp/api singleton — making it unsafe to route heartbeats or stop
-        // pokes to a specific ship. Disable entirely rather than route to the wrong ship.
+        // monitors call configureTlonApiWithPoke() and the last one wins the
+        // global @tloncorp/api singleton — making it unsafe to route heartbeats or
+        // stop pokes to a specific ship. Disable entirely rather than route to the
+        // wrong ship.
+        //
+        // We count ALL configured account entries (not just currently-runnable
+        // ones) on purpose. The manager is a process-lifetime singleton created
+        // here in registerFull, which does NOT re-run on config reload. If we
+        // counted only runnable accounts, a config of one complete account plus a
+        // disabled/unconfigured stub would enable the singleton, and later
+        // completing the stub would start a second monitor that races the shared
+        // API slot — without registerFull re-evaluating the gate. Counting every
+        // entry keeps the feature off whenever a second account exists at all.
         const gsAccountIds = listTlonAccountIds(api.config);
         setGatewayStatusManager(null);
         if (gsAccountIds.length > 1) {
@@ -187,26 +561,49 @@ export default defineChannelPluginEntry({
             const gsManager = createGatewayStatusManager({
                 logger: {
                     log: (m) => api.logger.info(m),
-                    error: (m) => api.logger.warn(m),
+                    error: (m) => {
+                        reportPluginError({
+                            pluginErrorSource: 'gateway_status_heartbeat',
+                            errorKind: 'heartbeat',
+                            errorText: m,
+                        });
+                        api.logger.warn(m);
+                    },
                 },
             });
             setGatewayStatusManager(gsManager);
-            api.on("gateway_start", () => {
+            api.on('gateway_start', () => {
                 gsManager.signalGatewayStarted();
-                api.logger.info("[gateway-status] gateway_start received");
+                api.logger.info('[gateway-status] gateway_start received');
             });
-            api.on("gateway_stop", async (event) => {
-                if (!gsManager.activated || gsManager.stopped) {
+            api.on('gateway_stop', async (event) => {
+                if (gsManager.stopped) {
                     return;
                 }
+                // Latch stopped FIRST, unconditionally. An activation task may be
+                // in flight (between the %gateway-start poke and markActivated());
+                // latching here makes its post-poke recheck bail so it can't start a
+                // heartbeat after we've already passed the shutdown hook.
+                const startPokeInFlightOrDone = gsManager.activated || gsManager.starting;
                 gsManager.stopHeartbeat();
                 gsManager.markStopped();
+                // Only send %gateway-stop if a %gateway-start has been or is being
+                // sent. If activation never reached the start poke, there is nothing
+                // for the ship to stop.
+                if (!startPokeInFlightOrDone) {
+                    return;
+                }
                 try {
-                    await gatewayStop({
+                    const sent = await sendGatewayStop({
                         bootId: gsManager.bootId,
-                        reason: event.reason ?? "shutdown",
+                        reason: event.reason ?? 'shutdown',
                     });
-                    api.logger.info(`[gateway-status] stopped (reason=${event.reason ?? "shutdown"})`);
+                    if (sent) {
+                        api.logger.info(`[gateway-status] stopped (reason=${event.reason ?? 'shutdown'})`);
+                    }
+                    else {
+                        api.logger.warn('[gateway-status] stop skipped: api-client params not published');
+                    }
                 }
                 catch (err) {
                     api.logger.warn(`[gateway-status] stop poke failed: ${String(err)}`);
@@ -214,21 +611,49 @@ export default defineChannelPluginEntry({
             });
         }
         // else: zero accounts configured — nothing to do
-        // Register /tlon-version command
-        api.registerCommand({
-            name: "tlon-version",
-            description: "Show Tlon plugin version.",
-            handler: async () => {
-                return { text: `Tlon plugin v${PLUGIN_VERSION} (${PLUGIN_COMMIT})` };
-            },
-        });
-        // Register the tlon tool
+        // Resolve the tlon tool binary once. The tool itself and version
+        // diagnostics share this path so telemetry reports what OpenClaw will
+        // actually execute.
         const tlonBinary = resolveTlonBinary({
             moduleDir: __dirname,
             resolveModule: require.resolve,
             log: (msg) => api.logger.debug?.(msg),
         });
         api.logger.info(`[tlon] Registering tlon tool, binary: ${tlonBinary}`);
+        setTlonSkillVersionResolver(() => readTlonSkillVersion(tlonBinary));
+        const renderTlonVersion = async () => ({
+            text: formatTlonVersionIdentity({
+                tlonSkillVersion: await resolveTlonSkillVersion(),
+            }),
+        });
+        void resolveTlonSkillVersion().then((version) => {
+            api.logger.info(`[tlon] Tlon skill version: ${version}`);
+        });
+        // Register /tlon-version command
+        api.registerCommand({
+            name: 'tlon-version',
+            description: 'Show Tlon plugin version.',
+            handler: async () => {
+                return renderTlonVersion();
+            },
+        });
+        api.registerCommand({
+            name: 'tlon',
+            description: 'Tlon plugin diagnostics. Usage: /tlon version',
+            acceptsArgs: true,
+            handler: async (ctx) => {
+                const args = (ctx.args ?? '').trim().toLowerCase();
+                if (args !== 'version') {
+                    return { text: 'Usage: /tlon version' };
+                }
+                const result = resolveBridgeForCommand(ctx);
+                if ('error' in result) {
+                    return { text: result.error };
+                }
+                return renderTlonVersion();
+            },
+        });
+        // Register the tlon tool
         // Capture credentials from config at registration time
         const account = resolveTlonAccount(api.config);
         const credentials = account.configured && account.url && account.ship && account.code
@@ -241,22 +666,22 @@ export default defineChannelPluginEntry({
             api.logger.warn(`[tlon] No credentials configured - tlon tool will rely on env vars`);
         }
         api.registerTool({
-            name: "tlon",
-            label: "Tlon CLI",
-            description: "Tlon/Urbit API for reading data and administration: activity, channels, contacts, groups, messages, posts, settings, upload, expose, hooks. " +
-                "DO NOT use this tool to send messages — use the `message` tool instead. " +
+            name: 'tlon',
+            label: 'Tlon CLI',
+            description: 'Tlon/Urbit API for reading data and administration: activity, channels, contacts, groups, messages, posts, settings, upload, expose, hooks. ' +
+                'DO NOT use this tool to send messages — use the `message` tool instead. ' +
                 "Examples: 'activity mentions --limit 10', 'channels groups', 'contacts self', 'groups list'",
             parameters: {
-                type: "object",
+                type: 'object',
                 properties: {
                     command: {
-                        type: "string",
-                        description: "The tlon command and arguments (read/admin operations). " +
-                            "To send messages, use the `message` tool, not this tool. " +
+                        type: 'string',
+                        description: 'The tlon command and arguments (read/admin operations). ' +
+                            'To send messages, use the `message` tool, not this tool. ' +
                             "Examples: 'activity mentions --limit 10', 'contacts get ~sampel-palnet', 'groups list', 'messages dm ~ship --limit 20'",
                     },
                 },
-                required: ["command"],
+                required: ['command'],
             },
             async execute(_id, params) {
                 try {
@@ -267,8 +692,8 @@ export default defineChannelPluginEntry({
                         return {
                             content: [
                                 {
-                                    type: "text",
-                                    text: `Error: Unknown tlon subcommand '${subcommand ?? "(none)"}'. Allowed: ${[...ALLOWED_TLON_COMMANDS].join(", ")}`,
+                                    type: 'text',
+                                    text: `Error: Unknown tlon subcommand '${subcommand ?? '(none)'}'. Allowed: ${[...ALLOWED_TLON_COMMANDS].join(', ')}`,
                                 },
                             ],
                             details: { error: true },
@@ -278,41 +703,43 @@ export default defineChannelPluginEntry({
                     const blocked = checkBlockedSendOperation(args.slice(subIdx));
                     if (blocked) {
                         return {
-                            content: [{ type: "text", text: blocked }],
-                            details: { blocked: true, reason: "send_operation" },
+                            content: [{ type: 'text', text: blocked }],
+                            details: { blocked: true, reason: 'send_operation' },
                         };
                     }
                     const output = await runTlonCommand(tlonBinary, args, credentials);
                     return {
-                        content: [{ type: "text", text: output }],
+                        content: [{ type: 'text', text: output }],
                         details: undefined,
                     };
                 }
                 catch (error) {
                     const message = error instanceof Error ? error.message : String(error);
                     return {
-                        content: [{ type: "text", text: `Error: ${message}` }],
+                        content: [{ type: 'text', text: `Error: ${message}` }],
                         details: { error: true },
                     };
                 }
             },
         });
         // Tool access control: block sensitive tools for non-owners
-        const ownerOnlyTools = new Set(["tlon", "cron", "read"]);
+        const ownerOnlyTools = new Set(['tlon', 'cron', 'read']);
         const logToolTraceContents = liveToolTraceContentsEnabled();
-        api.on("before_tool_call", (event, ctx) => {
-            const role = getSessionRole(ctx.sessionKey ?? "");
+        api.on('before_tool_call', (event, ctx) => {
+            const role = getSessionRole(ctx.sessionKey ?? '');
             const isOwnerOnlyTool = ownerOnlyTools.has(event.toolName);
-            const isBlocked = isOwnerOnlyTool && role === "user";
-            const blockReason = isBlocked ? `The ${event.toolName} tool is not available.` : undefined;
+            const isBlocked = isOwnerOnlyTool && role === 'user';
+            const blockReason = isBlocked
+                ? `The ${event.toolName} tool is not available.`
+                : undefined;
             if (logToolTraceContents) {
                 api.logger.info(formatToolTraceEvent({
-                    phase: "before",
+                    phase: 'before',
                     sessionKey: ctx.sessionKey,
                     toolName: event.toolName,
                     payload: {
                         params: event.params,
-                        role: role ?? "internal",
+                        role: role ?? 'internal',
                         blocked: isBlocked,
                         ...(blockReason ? { blockReason } : {}),
                     },
@@ -331,12 +758,12 @@ export default defineChannelPluginEntry({
                     blockReason,
                 };
             }
-            api.logger.info(`[tlon] Allowed ${event.toolName} tool for ${role ?? "internal"} session. Session: ${ctx.sessionKey}`);
+            api.logger.info(`[tlon] Allowed ${event.toolName} tool for ${role ?? 'internal'} session. Session: ${ctx.sessionKey}`);
         });
-        api.on("after_tool_call", (event, ctx) => {
+        api.on('after_tool_call', (event, ctx) => {
             if (logToolTraceContents && shouldLogAfterToolTrace(event)) {
                 api.logger.info(formatToolTraceEvent({
-                    phase: "after",
+                    phase: 'after',
                     sessionKey: ctx.sessionKey,
                     toolName: event.toolName,
                     payload: {
@@ -347,103 +774,227 @@ export default defineChannelPluginEntry({
                     },
                 }));
             }
-            recordToolCall({
+            safeTelemetryObserver({
+                logger: api.logger,
+                telemetrySource: 'after_tool_call',
+                sourceEventName: event.toolName,
                 sessionKey: ctx.sessionKey,
-                toolName: event.toolName,
-                durationMs: event.durationMs,
-                error: event.error,
+                run: () => {
+                    recordToolCall({
+                        sessionKey: ctx.sessionKey,
+                        toolName: event.toolName,
+                        durationMs: event.durationMs,
+                        error: event.error,
+                    });
+                },
+            });
+        });
+        // ── Session lifecycle / watchdog telemetry ─────────────────────────
+        // These hooks are global to OpenClaw, so telemetry.ts filters them through
+        // session keys remembered from Tlon inbound replies before emitting.
+        api.on('session_start', (event, ctx) => {
+            safeTelemetryObserver({
+                logger: api.logger,
+                telemetrySource: 'session_start',
+                sourceEventName: 'session_start',
+                sessionKey: event.sessionKey ?? ctx.sessionKey,
+                sessionId: event.sessionId ?? ctx.sessionId,
+                agentId: ctx.agentId,
+                run: () => {
+                    reportSessionLifecycle({
+                        lifecycleEvent: 'session_start',
+                        sessionKey: event.sessionKey ?? ctx.sessionKey,
+                        sessionId: event.sessionId ?? ctx.sessionId,
+                        agentId: ctx.agentId,
+                        hasNextSession: false,
+                    });
+                },
+            });
+        });
+        api.on('session_end', (event, ctx) => {
+            safeTelemetryObserver({
+                logger: api.logger,
+                telemetrySource: 'session_end',
+                sourceEventName: 'session_end',
+                sessionKey: event.sessionKey ?? ctx.sessionKey,
+                sessionId: event.sessionId ?? ctx.sessionId,
+                agentId: ctx.agentId,
+                run: () => {
+                    reportSessionLifecycle({
+                        lifecycleEvent: 'session_end',
+                        sessionKey: event.sessionKey ?? ctx.sessionKey,
+                        sessionId: event.sessionId ?? ctx.sessionId,
+                        agentId: ctx.agentId,
+                        reason: event.reason ?? null,
+                        messageCount: event.messageCount,
+                        durationMs: event.durationMs ?? null,
+                        transcriptArchived: event.transcriptArchived ?? null,
+                        hasNextSession: Boolean(event.nextSessionId ?? event.nextSessionKey),
+                    });
+                },
+            });
+        });
+        if (shouldInstallTlonDiagnosticSubscriptions(api.registrationMode)) {
+            const unsubscribeDiagnosticEvents = installTelemetryDiagnosticObservers(api);
+            api.on('gateway_stop', unsubscribeDiagnosticEvents);
+        }
+        // ── Route diagnostics ───────────────────────────────────────────────
+        // Fires for every outbound send OpenClaw routes — the primary streamed
+        // reply (resolves to `tlon`) and route-dependent sends (the shared
+        // `message` tool, subagents, which can resolve elsewhere). `ctx.channelId`
+        // is where the send resolved; `routedToTlon: false` (e.g. `webchat`) is the
+        // leak this work targets. Read-only; never alters delivery.
+        //
+        // Two sinks: a PostHog event (the primary, fleet-wide signal — gated by the
+        // existing telemetry config, on in hosted prod) so we can count how often
+        // sends land off-Tlon; and a debug-gated local log for single-gateway
+        // triage.
+        api.on('message_sending', (event, ctx) => {
+            safeTelemetryObserver({
+                logger: api.logger,
+                telemetrySource: 'message_sending',
+                sourceEventName: 'message_sending',
+                sessionKey: ctx.sessionKey,
+                runId: ctx.runId,
+                run: () => {
+                    const resolvedChannel = ctx.channelId;
+                    const routedToTlon = resolvedChannel === 'tlon';
+                    // Only infer target kind for Tlon targets; a webchat target id is not
+                    // a Tlon target and must not be misclassified.
+                    const parsedTarget = routedToTlon ? parseTlonTarget(event.to) : null;
+                    const targetKind = parsedTarget?.kind === 'dm'
+                        ? 'dm'
+                        : parsedTarget?.kind === 'channel'
+                            ? 'group'
+                            : 'unknown';
+                    reportOutboundRoute({ resolvedChannel, routedToTlon, targetKind });
+                    if (isRouteDebugEnabled()) {
+                        api.logger.info(`[tlon][route-debug] message_sending ${JSON.stringify({
+                            channelId: ctx.channelId,
+                            to: event.to,
+                            routedToTlon,
+                            targetKind,
+                            sessionKey: ctx.sessionKey ?? null,
+                            conversationId: ctx.conversationId ?? null,
+                            messageId: ctx.messageId ?? null,
+                            threadId: event.threadId ?? null,
+                        })}`);
+                    }
+                },
+            });
+        });
+        api.on('message_sent', (event, ctx) => {
+            safeTelemetryObserver({
+                logger: api.logger,
+                telemetrySource: 'message_sent',
+                sourceEventName: 'message_sent',
+                sessionKey: event.sessionKey ?? ctx.sessionKey,
+                runId: event.runId ?? ctx.runId,
+                run: () => {
+                    if (event.success !== false) {
+                        return;
+                    }
+                    reportHarnessError({
+                        harnessEventType: 'message_sent',
+                        errorScope: 'message_delivery',
+                        sessionKey: event.sessionKey ?? ctx.sessionKey,
+                        runId: event.runId ?? ctx.runId,
+                        errorText: event.error ?? null,
+                        outcome: 'error',
+                    });
+                },
             });
         });
         // ── Slash commands for approval & admin ────────────────────────────
         api.registerCommand({
-            name: "allow",
-            description: "Allow a pending DM/channel/group request",
+            name: 'allow',
+            description: 'Allow a pending DM/channel/group request',
             acceptsArgs: true,
             handler: async (ctx) => {
                 const result = resolveBridgeForCommand(ctx);
-                if ("error" in result) {
+                if ('error' in result) {
                     return { text: result.error };
                 }
                 return {
-                    text: await result.bridge.handleAction("approve", ctx.args?.trim() || undefined),
+                    text: await result.bridge.handleAction('approve', ctx.args?.trim() || undefined),
                 };
             },
         });
         api.registerCommand({
-            name: "reject",
-            description: "Reject a pending DM/channel/group request",
+            name: 'reject',
+            description: 'Reject a pending DM/channel/group request',
             acceptsArgs: true,
             handler: async (ctx) => {
                 const result = resolveBridgeForCommand(ctx);
-                if ("error" in result) {
+                if ('error' in result) {
                     return { text: result.error };
                 }
                 return {
-                    text: await result.bridge.handleAction("deny", ctx.args?.trim() || undefined),
+                    text: await result.bridge.handleAction('deny', ctx.args?.trim() || undefined),
                 };
             },
         });
         api.registerCommand({
-            name: "ban",
-            description: "Ban a ship and deny its pending request",
+            name: 'ban',
+            description: 'Ban a ship and deny its pending request',
             acceptsArgs: true,
             handler: async (ctx) => {
                 const result = resolveBridgeForCommand(ctx);
-                if ("error" in result) {
+                if ('error' in result) {
                     return { text: result.error };
                 }
                 return {
-                    text: await result.bridge.handleAction("block", ctx.args?.trim() || undefined),
+                    text: await result.bridge.handleAction('block', ctx.args?.trim() || undefined),
                 };
             },
         });
         api.registerCommand({
-            name: "pending",
-            description: "List pending approval requests",
+            name: 'pending',
+            description: 'List pending approval requests',
             handler: async (ctx) => {
                 const result = resolveBridgeForCommand(ctx);
-                if ("error" in result) {
+                if ('error' in result) {
                     return { text: result.error };
                 }
                 return { text: await result.bridge.getPendingList() };
             },
         });
         api.registerCommand({
-            name: "banned",
-            description: "List banned ships",
+            name: 'banned',
+            description: 'List banned ships',
             handler: async (ctx) => {
                 const result = resolveBridgeForCommand(ctx);
-                if ("error" in result) {
+                if ('error' in result) {
                     return { text: result.error };
                 }
                 return { text: await result.bridge.getBlockedList() };
             },
         });
         api.registerCommand({
-            name: "unban",
-            description: "Unban a ship (e.g. /unban ~sampel-palnet)",
+            name: 'unban',
+            description: 'Unban a ship (e.g. /unban ~sampel-palnet)',
             acceptsArgs: true,
             handler: async (ctx) => {
                 const result = resolveBridgeForCommand(ctx);
-                if ("error" in result) {
+                if ('error' in result) {
                     return { text: result.error };
                 }
                 const ship = ctx.args?.trim();
                 if (!ship) {
-                    return { text: "Usage: /unban ~ship-name" };
+                    return { text: 'Usage: /unban ~ship-name' };
                 }
                 return { text: await result.bridge.handleUnblock(ship) };
             },
         });
         api.registerCommand({
-            name: "owner-listen",
-            description: "Control whether the bot listens for the owner without @-mention in owned channels. " +
-                "Usage: /owner-listen [on|off|status|list] [<channel-nest>]; " +
-                "/owner-listen all [on|off] for the global kill switch.",
+            name: 'owner-listen',
+            description: 'Control whether the bot listens for the owner without @-mention in owned channels. ' +
+                'Usage: /owner-listen [on|off|status|list] [<channel-nest>]; ' +
+                '/owner-listen all [on|off] for the global kill switch.',
             acceptsArgs: true,
             handler: async (ctx) => {
                 const result = resolveBridgeForCommand(ctx);
-                if ("error" in result) {
+                if ('error' in result) {
                     return { text: result.error };
                 }
                 const text = await handleOwnerListenCommand(result.bridge, ctx.args, ctx.from);