@useorgx/openclaw-plugin 0.4.8 → 0.7.0

package/dist/index.js

@@ -13,202 +13,39 @@
 import { OrgXClient } from "./api.js";
 import { createHttpHandler } from "./http-handler.js";
 import { applyOrgxAgentSuitePlan, computeOrgxAgentSuitePlan } from "./agent-suite.js";
-import { registerArtifact } from "./artifacts/register-artifact.js";
+import { autoAssignEntityForCreate as autoAssignEntityForCreateWithClient, } from "./entities/auto-assignment.js";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
-import { fileURLToPath } from "node:url";
-import { createHash, randomUUID } from "node:crypto";
-import { clearPersistedApiKey, loadAuthStore, resolveInstallationId, saveAuthStore, } from "./auth-store.js";
+import { randomUUID } from "node:crypto";
+import { clearPersistedApiKey, loadAuthStore, resolveInstallationId, } from "./auth-store.js";
 import { clearPersistedSnapshot, readPersistedSnapshot, writePersistedSnapshot, } from "./snapshot-store.js";
-import { appendToOutbox, readOutbox, readOutboxSummary, replaceOutbox, } from "./outbox.js";
+import { appendToOutbox, readOutboxSummary, } from "./outbox.js";
 import { getAgentContext, readAgentContexts } from "./agent-context-store.js";
 import { readAgentRuns, markAgentRunStopped } from "./agent-run-store.js";
-import { extractProgressOutboxMessage } from "./reporting/outbox-replay.js";
-import { ensureGatewayWatchdog } from "./gateway-watchdog.js";
+import { ensureGatewayWatchdog, stopGatewayWatchdog } from "./gateway-watchdog.js";
 import { createMcpHttpHandler, } from "./mcp-http-handler.js";
-import { autoConfigureDetectedMcpClients } from "./mcp-client-setup.js";
-import { readOpenClawGatewayPort, readOpenClawSettingsSnapshot } from "./openclaw-settings.js";
 import { posthogCapture } from "./telemetry/posthog.js";
-import { readSkillPackState, refreshSkillPackState } from "./skill-pack-state.js";
+import { readSkillPackState, refreshSkillPackState, rollbackSkillPackPolicy, updateSkillPackPolicy, } from "./skill-pack-state.js";
+import { resolveConfig, resolveDocsUrl, resolveRuntimeUserId, } from "./config/resolution.js";
+import { refreshResolvedConfig } from "./config/refresh.js";
+import { applyRuntimeApiKey, buildManualKeyConnectUrl as buildManualKeyConnectUrlForBase, fetchOrgxJson as fetchOrgxJsonRequest, isAuthRequiredError, } from "./auth/flows.js";
+import { registerOrgxCli } from "./cli/orgx.js";
+import { instrumentPluginApi } from "./services/instrumentation.js";
+import { registerSyncService } from "./services/background.js";
+import { stopDetachedProcess } from "./http/helpers/openclaw-cli.js";
+import { createOutboxReplayer } from "./sync/outbox-replay.js";
+import { buildLocalAgentMirrorsFromSnapshot, buildLocalSyncAgentsFromRuns, } from "./sync/local-agent-telemetry.js";
+import { registerCoreTools } from "./tools/core-tools.js";
+import { stableHash } from "./hash-utils.js";
+import { RETRO_ARTIFACT_SCHEMA_VERSION } from "./contracts/retro-schema.js";
+import { buildRetroWithLlm } from "./retro/domain-templates.js";
+import { computeRetroQualityRubricScore } from "./retro/quality-rubric.js";
 export { OrgXClient } from "./api.js";
-const DEFAULT_BASE_URL = "https://www.useorgx.com";
-const DEFAULT_DOCS_URL = "https://orgx.mintlify.site/guides/openclaw-plugin-setup";
-function isUserScopedApiKey(apiKey) {
-    return apiKey.trim().toLowerCase().startsWith("oxk_");
-}
-function resolveRuntimeUserId(apiKey, candidates) {
-    if (isUserScopedApiKey(apiKey)) {
-        // For oxk_ keys, the OrgX API ignores X-Orgx-User-Id, but we still keep a UUID
-        // around for created_by_id on certain entity writes (e.g., work_artifacts).
-        for (const candidate of candidates) {
-            if (typeof candidate !== "string")
-                continue;
-            const trimmed = candidate.trim();
-            if (/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(trimmed)) {
-                return trimmed;
-            }
-        }
-        return "";
-    }
-    for (const candidate of candidates) {
-        if (typeof candidate === "string") {
-            const trimmed = candidate.trim();
-            if (trimmed.length > 0)
-                return trimmed;
-        }
-    }
-    return "";
-}
-function normalizeHost(value) {
-    return value.trim().toLowerCase().replace(/^\[|\]$/g, "");
-}
-function isLoopbackHostname(hostname) {
-    const normalized = normalizeHost(hostname);
-    return normalized === "localhost" || normalized === "127.0.0.1" || normalized === "::1";
-}
-function normalizeBaseUrl(raw) {
-    const candidate = raw?.trim() ?? "";
-    if (!candidate) {
-        return DEFAULT_BASE_URL;
-    }
-    try {
-        const parsed = new URL(candidate);
-        if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
-            return DEFAULT_BASE_URL;
-        }
-        // Do not allow credential-bearing URLs.
-        if (parsed.username || parsed.password) {
-            return DEFAULT_BASE_URL;
-        }
-        // Plain HTTP is only allowed for local loopback development.
-        if (parsed.protocol === "http:" && !isLoopbackHostname(parsed.hostname)) {
-            return DEFAULT_BASE_URL;
-        }
-        parsed.search = "";
-        parsed.hash = "";
-        const normalizedPath = parsed.pathname.replace(/\/+$/, "");
-        parsed.pathname = normalizedPath;
-        const normalized = parsed.toString().replace(/\/+$/, "");
-        return normalized.length > 0 ? normalized : DEFAULT_BASE_URL;
-    }
-    catch {
-        return DEFAULT_BASE_URL;
-    }
-}
-function readLegacyEnvValue(keyPattern) {
-    try {
-        const envPath = join(homedir(), "Code", "orgx", "orgx", ".env.local");
-        const envContent = readFileSync(envPath, "utf-8");
-        const match = envContent.match(keyPattern);
-        return match?.[1]?.trim() ?? "";
-    }
-    catch {
-        return "";
-    }
-}
-function readOpenClawOrgxConfig() {
-    try {
-        const configPath = join(homedir(), ".openclaw", "openclaw.json");
-        const raw = readFileSync(configPath, "utf8");
-        const parsed = JSON.parse(raw);
-        const plugins = parsed.plugins && typeof parsed.plugins === "object"
-            ? parsed.plugins
-            : {};
-        const entries = plugins.entries && typeof plugins.entries === "object"
-            ? plugins.entries
-            : {};
-        const orgx = entries.orgx && typeof entries.orgx === "object"
-            ? entries.orgx
-            : {};
-        const config = orgx.config && typeof orgx.config === "object"
-            ? orgx.config
-            : {};
-        const apiKey = typeof config.apiKey === "string" ? config.apiKey.trim() : "";
-        const userId = typeof config.userId === "string" ? config.userId.trim() : "";
-        const baseUrl = typeof config.baseUrl === "string" ? config.baseUrl.trim() : "";
-        return { apiKey, userId, baseUrl };
-    }
-    catch {
-        return { apiKey: "", userId: "", baseUrl: "" };
-    }
-}
-function resolveApiKey(pluginConf, persistedApiKey) {
-    if (pluginConf.apiKey && pluginConf.apiKey.trim().length > 0) {
-        return { value: pluginConf.apiKey.trim(), source: "config" };
-    }
-    if (process.env.ORGX_API_KEY && process.env.ORGX_API_KEY.trim().length > 0) {
-        return { value: process.env.ORGX_API_KEY.trim(), source: "environment" };
-    }
-    if (persistedApiKey && persistedApiKey.trim().length > 0) {
-        return { value: persistedApiKey.trim(), source: "persisted" };
-    }
-    const openclaw = readOpenClawOrgxConfig();
-    if (openclaw.apiKey) {
-        return { value: openclaw.apiKey, source: "openclaw-config-file" };
-    }
-    // For local dev convenience we read `ORGX_API_KEY` from `~/Code/orgx/orgx/.env.local`.
-    // Do not auto-consume `ORGX_SERVICE_KEY` because service keys often require `X-Orgx-User-Id`,
-    // and the dashboard/client flows are intended to run on user-scoped keys (`oxk_...`).
-    const legacy = readLegacyEnvValue(/^ORGX_API_KEY=["']?([^"'\n]+)["']?$/m);
-    if (legacy) {
-        return { value: legacy, source: "legacy-dev" };
-    }
-    return { value: "", source: "none" };
-}
-function resolvePluginVersion() {
-    try {
-        const packagePath = fileURLToPath(new URL("../package.json", import.meta.url));
-        const parsed = JSON.parse(readFileSync(packagePath, "utf8"));
-        return parsed.version && parsed.version.trim().length > 0
-            ? parsed.version
-            : "dev";
-    }
-    catch {
-        return "dev";
-    }
-}
-function resolveDocsUrl(baseUrl) {
-    const normalized = baseUrl.replace(/\/+$/, "");
-    try {
-        const parsed = new URL(normalized);
-        if (isLoopbackHostname(parsed.hostname)) {
-            return `${normalized}/docs/mintlify/guides/openclaw-plugin-setup`;
-        }
-    }
-    catch {
-        return DEFAULT_DOCS_URL;
-    }
-    return DEFAULT_DOCS_URL;
-}
-function resolveConfig(api, input) {
-    const pluginConf = api.config?.plugins?.entries?.orgx?.config ?? {};
-    const openclaw = readOpenClawOrgxConfig();
-    const apiKeyResolution = resolveApiKey(pluginConf, input.persistedApiKey);
-    const apiKey = apiKeyResolution.value;
-    // Resolve user ID for X-Orgx-User-Id header
-    const userId = resolveRuntimeUserId(apiKey, [
-        pluginConf.userId,
-        process.env.ORGX_USER_ID,
-        input.persistedUserId,
-        openclaw.userId,
-        readLegacyEnvValue(/^ORGX_USER_ID=["']?([^"'\n]+)["']?$/m),
-    ]);
-    const baseUrl = normalizeBaseUrl(pluginConf.baseUrl || process.env.ORGX_BASE_URL || openclaw.baseUrl || DEFAULT_BASE_URL);
-    return {
-        apiKey,
-        userId,
-        baseUrl,
-        syncIntervalMs: pluginConf.syncIntervalMs ?? 300_000,
-        enabled: pluginConf.enabled ?? true,
-        autoInstallAgentSuiteOnConnect: pluginConf.autoInstallAgentSuiteOnConnect ?? true,
-        dashboardEnabled: pluginConf.dashboardEnabled ?? true,
-        installationId: input.installationId,
-        pluginVersion: resolvePluginVersion(),
-        docsUrl: resolveDocsUrl(baseUrl),
-        apiKeySource: apiKeyResolution.source,
-    };
-}
+const ORGX_CANONICAL_BASE_URL = "https://www.useorgx.com";
+// =============================================================================
+// HELPERS
+// =============================================================================
 function text(s) {
     return { content: [{ type: "text", text: s }] };
 }
@@ -407,55 +244,17 @@ export default function register(api) {
     const defaultReportingCorrelationId = pickNonEmptyString(process.env.ORGX_CORRELATION_ID) ??
         `openclaw-${config.installationId}`;
     function refreshConfigFromSources(input) {
-        const allowApiKeyChanges = input?.allowApiKeyChanges !== false;
-        const previousApiKey = config.apiKey;
-        const previousBaseUrl = config.baseUrl;
-        const previousUserId = config.userId;
-        const previousDocsUrl = config.docsUrl;
-        const previousKeySource = config.apiKeySource;
-        const latestPersisted = loadAuthStore();
-        const next = resolveConfig(api, {
-            installationId: config.installationId,
-            persistedApiKey: latestPersisted?.apiKey ?? null,
-            persistedUserId: latestPersisted?.userId ?? null,
-        });
-        const nextApiKey = allowApiKeyChanges ? next.apiKey : previousApiKey;
-        const nextUserId = allowApiKeyChanges ? next.userId : previousUserId;
-        const changed = nextApiKey !== previousApiKey ||
-            next.baseUrl !== previousBaseUrl ||
-            nextUserId !== previousUserId ||
-            next.docsUrl !== previousDocsUrl ||
-            next.apiKeySource !== previousKeySource;
-        if (!changed) {
-            return false;
-        }
-        if (allowApiKeyChanges) {
-            config.apiKey = nextApiKey;
-            config.userId = nextUserId;
-            config.apiKeySource = next.apiKeySource;
-        }
-        config.baseUrl = next.baseUrl;
-        config.docsUrl = next.docsUrl;
-        baseApiUrl = config.baseUrl.replace(/\/+$/, "");
-        client.setCredentials({
-            apiKey: config.apiKey,
-            userId: config.userId,
-            baseUrl: config.baseUrl,
-        });
-        // Keep onboarding state aligned with what's actually configured (without forcing a status transition).
-        updateOnboardingState({
-            hasApiKey: Boolean(config.apiKey),
-            keySource: config.apiKeySource,
-            docsUrl: config.docsUrl,
-            installationId: config.installationId,
-        });
-        api.log?.info?.("[orgx] Config refreshed", {
-            reason: input?.reason ?? "runtime_refresh",
-            baseUrl: config.baseUrl,
-            hasApiKey: Boolean(config.apiKey),
-            apiKeySource: config.apiKeySource,
-        });
-        return true;
+        const refreshed = refreshResolvedConfig({
+            api,
+            config,
+            loadAuthStore,
+            resolveConfig,
+            updateOnboardingState,
+            setCredentials: (credentials) => client.setCredentials(credentials),
+            logInfo: api.log?.info,
+        }, input);
+        baseApiUrl = refreshed.baseApiUrl;
+        return refreshed.changed;
     }
     function resolveReportingContext(input) {
         let initiativeId = pickNonEmptyString(input.initiative_id, input.initiativeId, process.env.ORGX_INITIATIVE_ID);
@@ -505,9 +304,6 @@ export default function register(api) {
             return err.message;
         return typeof err === "string" ? err : "Unexpected error";
     }
-    function stableHash(value) {
-        return createHash("sha256").update(value).digest("hex");
-    }
     function isAuthFailure(err) {
         const message = toErrorMessage(err).toLowerCase();
         return (message.includes("401") ||
@@ -515,140 +311,12 @@ export default function register(api) {
             message.includes("invalid_token") ||
             message.includes("invalid api key"));
     }
-    const registerTool = api.registerTool.bind(api);
-    api.registerTool = (tool, options) => {
-        const toolName = tool.name;
-        const optional = Boolean(options?.optional);
-        registerTool({
-            ...tool,
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            execute: async (callId, params) => {
-                const startedAt = Date.now();
-                void posthogCapture({
-                    event: "openclaw_tool_called",
-                    distinctId: config.installationId,
-                    properties: {
-                        tool_name: toolName,
-                        tool_optional: optional,
-                        call_id: callId,
-                        plugin_version: config.pluginVersion,
-                    },
-                }).catch(() => {
-                    // best effort
-                });
-                try {
-                    const result = await tool.execute(callId, params);
-                    const durationMs = Date.now() - startedAt;
-                    void posthogCapture({
-                        event: "openclaw_tool_succeeded",
-                        distinctId: config.installationId,
-                        properties: {
-                            tool_name: toolName,
-                            tool_optional: optional,
-                            call_id: callId,
-                            duration_ms: durationMs,
-                            plugin_version: config.pluginVersion,
-                        },
-                    }).catch(() => {
-                        // best effort
-                    });
-                    return result;
-                }
-                catch (err) {
-                    const durationMs = Date.now() - startedAt;
-                    void posthogCapture({
-                        event: "openclaw_tool_failed",
-                        distinctId: config.installationId,
-                        properties: {
-                            tool_name: toolName,
-                            tool_optional: optional,
-                            call_id: callId,
-                            duration_ms: durationMs,
-                            plugin_version: config.pluginVersion,
-                            error: toErrorMessage(err),
-                        },
-                    }).catch(() => {
-                        // best effort
-                    });
-                    throw err;
-                }
-            },
-        }, options);
-    };
-    const registerService = api.registerService.bind(api);
-    api.registerService = (service) => {
-        registerService({
-            ...service,
-            start: async () => {
-                const startedAt = Date.now();
-                try {
-                    await service.start();
-                    const durationMs = Date.now() - startedAt;
-                    void posthogCapture({
-                        event: "openclaw_service_started",
-                        distinctId: config.installationId,
-                        properties: {
-                            service_id: service.id,
-                            duration_ms: durationMs,
-                            plugin_version: config.pluginVersion,
-                        },
-                    }).catch(() => {
-                        // best effort
-                    });
-                }
-                catch (err) {
-                    const durationMs = Date.now() - startedAt;
-                    void posthogCapture({
-                        event: "openclaw_service_start_failed",
-                        distinctId: config.installationId,
-                        properties: {
-                            service_id: service.id,
-                            duration_ms: durationMs,
-                            plugin_version: config.pluginVersion,
-                            error: toErrorMessage(err),
-                        },
-                    }).catch(() => {
-                        // best effort
-                    });
-                    throw err;
-                }
-            },
-            stop: async () => {
-                const startedAt = Date.now();
-                try {
-                    await service.stop();
-                    const durationMs = Date.now() - startedAt;
-                    void posthogCapture({
-                        event: "openclaw_service_stopped",
-                        distinctId: config.installationId,
-                        properties: {
-                            service_id: service.id,
-                            duration_ms: durationMs,
-                            plugin_version: config.pluginVersion,
-                        },
-                    }).catch(() => {
-                        // best effort
-                    });
-                }
-                catch (err) {
-                    const durationMs = Date.now() - startedAt;
-                    void posthogCapture({
-                        event: "openclaw_service_stop_failed",
-                        distinctId: config.installationId,
-                        properties: {
-                            service_id: service.id,
-                            duration_ms: durationMs,
-                            plugin_version: config.pluginVersion,
-                            error: toErrorMessage(err),
-                        },
-                    }).catch(() => {
-                        // best effort
-                    });
-                    throw err;
-                }
-            },
-        });
-    };
+    instrumentPluginApi({
+        api,
+        installationId: config.installationId,
+        pluginVersion: config.pluginVersion,
+        toErrorMessage,
+    });
     function clearPairingState() {
         activePairing = null;
         updateOnboardingState({
@@ -658,166 +326,55 @@ export default function register(api) {
             pollIntervalMs: null,
         });
     }
-    function isAuthRequiredError(result) {
-        if (result.status !== 401) {
-            return false;
-        }
-        return /auth|unauthorized|token/i.test(result.error);
-    }
     function buildManualKeyConnectUrl() {
-        try {
-            // Deep-link into the Security section where API keys live.
-            return new URL("/settings#security", baseApiUrl).toString();
-        }
-        catch {
-            return "https://www.useorgx.com/settings#security";
-        }
+        return buildManualKeyConnectUrlForBase(baseApiUrl);
     }
     async function fetchOrgxJson(method, path, body, options) {
-        try {
-            const controller = new AbortController();
-            const timeoutMs = typeof options?.timeoutMs === "number" && Number.isFinite(options.timeoutMs)
-                ? Math.max(1_000, Math.floor(options.timeoutMs))
-                : 12_000;
-            const timeout = setTimeout(() => controller.abort(), timeoutMs);
-            let response;
-            let rawText = "";
-            try {
-                response = await fetch(`${baseApiUrl}${path}`, {
-                    method,
-                    signal: controller.signal,
-                    headers: {
-                        Accept: "application/json",
-                        "Content-Type": "application/json",
-                    },
-                    body: body ? JSON.stringify(body) : undefined,
-                });
-                rawText = await response.text().catch(() => "");
-            }
-            finally {
-                clearTimeout(timeout);
-            }
-            const payload = (() => {
-                if (!rawText)
-                    return null;
-                try {
-                    return JSON.parse(rawText);
-                }
-                catch {
-                    return null;
-                }
-            })();
-            if (!response.ok) {
-                const rawError = payload?.error ?? payload?.message;
-                let errorMessage;
-                if (typeof rawError === "string") {
-                    errorMessage = rawError;
-                }
-                else if (rawError &&
-                    typeof rawError === "object" &&
-                    "message" in rawError &&
-                    typeof rawError.message === "string") {
-                    errorMessage = rawError.message;
-                }
-                else if (rawText && rawText.trim().length > 0) {
-                    // Avoid dumping HTML (Cloudflare / Next.js error pages) into UI; keep it short.
-                    const sanitized = rawText
-                        .replace(/\s+/g, " ")
-                        .replace(/<[^>]+>/g, "")
-                        .trim();
-                    errorMessage = sanitized.length > 0 ? sanitized.slice(0, 180) : `OrgX request failed (${response.status})`;
-                }
-                else {
-                    errorMessage = `OrgX request failed (${response.status})`;
-                }
-                const statusToken = `HTTP ${response.status}`;
-                if (response.status &&
-                    !errorMessage.toLowerCase().includes(statusToken.toLowerCase()) &&
-                    !errorMessage.includes(`(${response.status})`)) {
-                    errorMessage = `${errorMessage} (HTTP ${response.status})`;
-                }
-                const debugParts = [];
-                const requestId = response.headers.get("x-request-id");
-                const vercelId = response.headers.get("x-vercel-id");
-                const cfRay = response.headers.get("cf-ray");
-                const clerkStatus = response.headers.get("x-clerk-auth-status");
-                const clerkReason = response.headers.get("x-clerk-auth-reason");
-                if (requestId)
-                    debugParts.push(`req=${requestId}`);
-                if (vercelId && vercelId !== requestId)
-                    debugParts.push(`vercel=${vercelId}`);
-                if (cfRay)
-                    debugParts.push(`cf-ray=${cfRay}`);
-                if (clerkStatus)
-                    debugParts.push(`clerk=${clerkStatus}`);
-                if (clerkReason)
-                    debugParts.push(`clerk_reason=${clerkReason}`);
-                const debugSuffix = debugParts.length > 0 ? ` (${debugParts.join(", ")})` : "";
-                return {
-                    ok: false,
-                    status: response.status,
-                    error: `${errorMessage}${debugSuffix}`,
-                };
-            }
-            if (payload?.data !== undefined) {
-                return { ok: true, data: payload.data };
-            }
-            if (payload !== null) {
-                return { ok: true, data: payload };
-            }
-            return { ok: true, data: rawText };
-        }
-        catch (err) {
-            const message = err &&
-                typeof err === "object" &&
-                "name" in err &&
-                err.name === "AbortError"
-                ? `OrgX request timed out (method=${method}, path=${path})`
-                : toErrorMessage(err);
-            return { ok: false, status: 0, error: message };
-        }
+        return fetchOrgxJsonRequest({
+            baseApiUrl,
+            method,
+            path,
+            body,
+            options,
+            toErrorMessage,
+        });
     }
-    function setRuntimeApiKey(input) {
-        const nextApiKey = input.apiKey.trim();
-        config.apiKey = nextApiKey;
-        config.apiKeySource = "persisted";
-        config.userId = resolveRuntimeUserId(nextApiKey, [input.userId, config.userId]);
+    function looksLikeTransientFetchFailure(message) {
+        const normalized = message.toLowerCase();
+        return (normalized.includes("fetch failed") ||
+            normalized.includes("networkerror") ||
+            normalized.includes("econnrefused") ||
+            normalized.includes("enotfound") ||
+            normalized.includes("eai_again"));
+    }
+    function applyRuntimeBaseUrl(nextBaseUrl) {
+        const normalized = nextBaseUrl.trim().replace(/\/+$/, "");
+        if (!normalized)
+            return;
+        if (config.baseUrl === normalized && baseApiUrl === normalized)
+            return;
+        config.baseUrl = normalized;
+        baseApiUrl = normalized;
         client.setCredentials({
             apiKey: config.apiKey,
             userId: config.userId,
             baseUrl: config.baseUrl,
         });
-        saveAuthStore({
-            installationId: config.installationId,
-            apiKey: nextApiKey,
-            userId: config.userId || null,
-            workspaceName: input.workspaceName ?? null,
-            keyPrefix: input.keyPrefix ?? null,
+        updateOnboardingState({ docsUrl: resolveDocsUrl(config.baseUrl) });
+    }
+    function setRuntimeApiKey(input) {
+        applyRuntimeApiKey({
+            config,
+            apiKey: input.apiKey,
             source: input.source,
+            workspaceName: input.workspaceName,
+            keyPrefix: input.keyPrefix,
+            userId: input.userId,
+            currentWorkspaceName: onboardingState.workspaceName,
+            updateOnboardingState,
+            setCredentials: (credentials) => client.setCredentials(credentials),
+            logger: api.log ?? {},
         });
-        updateOnboardingState({
-            hasApiKey: true,
-            keySource: "persisted",
-            installationId: config.installationId,
-            workspaceName: input.workspaceName ?? onboardingState.workspaceName,
-        });
-        if (input.source === "browser_pairing" &&
-            process.env.ORGX_DISABLE_MCP_CLIENT_AUTOCONFIG !== "1") {
-            try {
-                const snapshot = readOpenClawSettingsSnapshot();
-                const port = readOpenClawGatewayPort(snapshot.raw);
-                const localMcpUrl = `http://127.0.0.1:${port}/orgx/mcp`;
-                void autoConfigureDetectedMcpClients({
-                    localMcpUrl,
-                    logger: api.log ?? {},
-                }).catch(() => {
-                    // best effort
-                });
-            }
-            catch {
-                // best effort
-            }
-        }
     }
     // ---------------------------------------------------------------------------
     // 1. Background Sync Service
@@ -825,6 +382,7 @@ export default function register(api) {
     let syncTimer = null;
     let syncInFlight = null;
     let syncServiceRunning = false;
+    let localAgentMirrors = [];
     let outboxReplayState = {
         status: "idle",
         lastReplayAttemptAt: null,
@@ -1133,6 +691,24 @@ export default function register(api) {
                 const completedAt = stopped.stoppedAt ?? new Date().toISOString();
                 const success = !summary.hadError;
                 const correlationId = stopped.runId;
+                const retroTemplate = await buildRetroWithLlm({
+                    agentId: stopped.agentId,
+                    success,
+                    taskId: stopped.taskId,
+                    runId: stopped.runId,
+                    errorMessage: summary.errorMessage,
+                });
+                const retroSummary = retroTemplate.summary;
+                const retroQuality = computeRetroQualityRubricScore({
+                    success,
+                    hadError: summary.hadError,
+                    errorMessage: summary.errorMessage,
+                    tokens: summary.tokens,
+                    costUsd: summary.costUsd,
+                    decisionsCount: retroTemplate.decisions.length,
+                    followUpsCount: retroTemplate.followUps.length,
+                    whatWentWrongCount: retroTemplate.whatWentWrong.length,
+                });
                 const outcomePayload = {
                     initiative_id: initiativeId,
                     correlation_id: correlationId,
@@ -1154,6 +730,7 @@ export default function register(api) {
                     },
                     steps: [],
                     success,
+                    quality_score: retroQuality.score,
                     human_interventions: 0,
                     errors: summary.errorMessage ? [summary.errorMessage] : [],
                     metadata: {
@@ -1168,9 +745,6 @@ export default function register(api) {
                     ? "task"
                     : "initiative";
                 const retroEntityId = stopped.taskId ?? initiativeId;
-                const retroSummary = stopped.taskId
-                    ? `OpenClaw ${success ? "completed" : "blocked"} task ${stopped.taskId}.`
-                    : `OpenClaw run ${success ? "completed" : "blocked"} (session ${stopped.runId}).`;
                 const retroPayload = {
                     initiative_id: initiativeId,
                     correlation_id: correlationId,
@@ -1180,21 +754,12 @@ export default function register(api) {
                     title: stopped.taskId ?? stopped.runId,
                     idempotency_key: `retro:${stopped.runId}`,
                     retro: {
+                        schema_version: RETRO_ARTIFACT_SCHEMA_VERSION,
                         summary: retroSummary,
-                        what_went_well: success ? ["Completed without runtime error."] : [],
-                        what_went_wrong: success
-                            ? []
-                            : [summary.errorMessage ?? "Session ended with error."],
-                        decisions: [],
-                        follow_ups: success
-                            ? []
-                            : [
-                                {
-                                    title: "Investigate OpenClaw session failure and unblock task",
-                                    priority: "p0",
-                                    reason: summary.errorMessage ?? "Session ended with error.",
-                                },
-                            ],
+                        what_went_well: retroTemplate.whatWentWell,
+                        what_went_wrong: retroTemplate.whatWentWrong,
+                        decisions: retroTemplate.decisions,
+                        follow_ups: retroTemplate.followUps,
                         signals: {
                             tokens: summary.tokens,
                             cost_usd: summary.costUsd,
@@ -1203,8 +768,11 @@ export default function register(api) {
                             session_id: stopped.runId,
                             task_id: stopped.taskId,
                             workstream_id: stopped.workstreamId,
+                            domain: retroTemplate.domain,
                             provider: stopped.provider,
                             model: stopped.model,
+                            quality_score: retroQuality.score,
+                            quality_rubric_reasons: retroQuality.reasons,
                             source: "openclaw_agent_run_reconcile",
                         },
                     },
@@ -1283,541 +851,75 @@ export default function register(api) {
             // best effort
         }
     }
-    async function replayOutboxEvent(event) {
-        const payload = event.payload ?? {};
-        function normalizeRunFields(context) {
-            // We prefer correlation IDs for replay because many local adapters use UUID-like
-            // session IDs that do *not* exist as server-side run IDs.
-            if (context.correlationId) {
-                return { run_id: undefined, correlation_id: context.correlationId };
-            }
-            if (context.runId) {
-                return {
-                    run_id: undefined,
-                    correlation_id: `openclaw_run_${stableHash(context.runId).slice(0, 24)}`,
-                };
-            }
-            return { run_id: undefined, correlation_id: undefined };
+    const { flushOutboxQueues } = createOutboxReplayer({
+        client,
+        logger: api.log ?? {},
+        toErrorMessage,
+        stableHash,
+        resolveReportingContext,
+        pickStringField,
+        pickStringArrayField,
+        toReportingPhase,
+        parseRetroEntityType,
+        isUuid,
+        readOutboxReplayState: () => outboxReplayState,
+        writeOutboxReplayState: (next) => {
+            outboxReplayState = next;
+        },
+    });
+    async function doSync() {
+        if (syncInFlight) {
+            return syncInFlight;
         }
-        if (event.type === "progress") {
-            const message = extractProgressOutboxMessage(payload);
-            if (!message) {
-                api.log?.warn?.("[orgx] Dropping invalid progress outbox event", {
-                    eventId: event.id,
+        syncInFlight = (async () => {
+            if (!config.apiKey) {
+                refreshConfigFromSources({ reason: "sync_no_api_key" });
+            }
+            if (!config.apiKey) {
+                updateOnboardingState({
+                    status: "idle",
+                    hasApiKey: false,
+                    connectionVerified: false,
+                    nextAction: "connect",
                 });
                 return;
             }
-            const context = resolveReportingContext(payload);
-            if (!context.ok) {
-                throw new Error(context.error);
-            }
-            const rawPhase = pickStringField(payload, "phase") ?? "implementing";
-            const progressPct = typeof payload.progress_pct === "number"
-                ? payload.progress_pct
-                : typeof payload.progressPct === "number"
-                    ? payload.progressPct
-                    : undefined;
-            const phase = rawPhase === "intent" ||
-                rawPhase === "execution" ||
-                rawPhase === "blocked" ||
-                rawPhase === "review" ||
-                rawPhase === "handoff" ||
-                rawPhase === "completed"
-                ? rawPhase
-                : toReportingPhase(rawPhase, progressPct);
-            const metaRaw = payload.metadata;
-            const meta = metaRaw && typeof metaRaw === "object" && !Array.isArray(metaRaw)
-                ? metaRaw
-                : {};
-            const baseMetadata = {
-                ...meta,
-                source: "orgx_openclaw_outbox_replay",
-                outbox_event_id: event.id,
-            };
-            let emitPayload = {
-                initiative_id: context.value.initiativeId,
-                run_id: context.value.runId,
-                correlation_id: context.value.correlationId,
-                source_client: context.value.sourceClient,
-                message,
-                phase,
-                progress_pct: progressPct,
-                level: pickStringField(payload, "level"),
-                next_step: pickStringField(payload, "next_step") ??
-                    pickStringField(payload, "nextStep") ??
-                    undefined,
-                metadata: baseMetadata,
-            };
-            // Locally-buffered progress events often store a local UUID in run_id. OrgX may reject
-            // unknown run IDs on replay; prefer a deterministic non-UUID correlation key instead.
-            if (emitPayload.run_id && !emitPayload.correlation_id) {
-                const replayCorrelationId = `openclaw_run_${stableHash(emitPayload.run_id).slice(0, 24)}`;
-                emitPayload = {
-                    ...emitPayload,
-                    run_id: undefined,
-                    correlation_id: replayCorrelationId,
-                    metadata: {
-                        ...(emitPayload.metadata ?? {}),
-                        replay_run_id_as_correlation: true,
-                    },
-                };
-            }
             try {
-                await client.emitActivity(emitPayload);
-            }
-            catch (err) {
-                // Some locally-buffered events carry a UUID that *looks* like an OrgX run_id
-                // but was only ever used as a local correlation/grouping key. If OrgX
-                // doesn't recognize it, retry by treating it as correlation_id so OrgX can
-                // create/attach a run deterministically.
-                const msg = toErrorMessage(err);
-                if (emitPayload.run_id &&
-                    /^404\\b/.test(msg) &&
-                    /\\brun\\b/i.test(msg) &&
-                    /not found/i.test(msg)) {
-                    const replayCorrelationId = `openclaw_run_${stableHash(emitPayload.run_id).slice(0, 24)}`;
-                    await client.emitActivity({
-                        ...emitPayload,
-                        run_id: undefined,
-                        correlation_id: replayCorrelationId,
-                        metadata: {
-                            ...(emitPayload.metadata ?? {}),
-                            replay_run_id_as_correlation: true,
-                        },
+                await reconcileStoppedAgentRuns();
+                let snapshotError = null;
+                try {
+                    const snapshot = await client.getOrgSnapshot();
+                    updateCachedSnapshot(snapshot);
+                    localAgentMirrors = buildLocalAgentMirrorsFromSnapshot({
+                        agents: snapshot.agents,
                     });
                 }
-                else {
-                    throw err;
+                catch (err) {
+                    if (isAuthFailure(err)) {
+                        throw err;
+                    }
+                    snapshotError = toErrorMessage(err);
+                    api.log?.warn?.("[orgx] Snapshot sync failed (continuing)", {
+                        error: snapshotError,
+                    });
                 }
-            }
-            return;
-        }
-        if (event.type === "decision") {
-            const question = pickStringField(payload, "question");
-            if (!question) {
-                api.log?.warn?.("[orgx] Dropping invalid decision outbox event", {
-                    eventId: event.id,
-                });
-                return;
-            }
-            const context = resolveReportingContext(payload);
-            if (!context.ok) {
-                throw new Error(context.error);
-            }
-            const runFields = normalizeRunFields({
-                runId: context.value.runId,
-                correlationId: context.value.correlationId,
-            });
-            // Payloads should include a stable idempotency_key when enqueued, but older
-            // events may not. Derive a deterministic fallback so outbox replay won't
-            // double-create the same remote decision.
-            const fallbackKey = stableHash(JSON.stringify({
-                t: "decision",
-                initiative_id: context.value.initiativeId,
-                run_id: context.value.runId ?? null,
-                correlation_id: context.value.correlationId ?? null,
-                question,
-            })).slice(0, 24);
-            const resolvedIdempotencyKey = pickStringField(payload, "idempotency_key") ??
-                pickStringField(payload, "idempotencyKey") ??
-                `openclaw:decision:${fallbackKey}`;
-            await client.applyChangeset({
-                initiative_id: context.value.initiativeId,
-                run_id: runFields.run_id,
-                correlation_id: runFields.correlation_id,
-                source_client: context.value.sourceClient,
-                idempotency_key: resolvedIdempotencyKey,
-                operations: [
-                    {
-                        op: "decision.create",
-                        title: question,
-                        summary: pickStringField(payload, "context") ?? undefined,
-                        urgency: pickStringField(payload, "urgency") ?? "medium",
-                        options: pickStringArrayField(payload, "options"),
-                        blocking: typeof payload.blocking === "boolean" ? payload.blocking : true,
-                    },
-                ],
-            });
-            return;
-        }
-        if (event.type === "changeset") {
-            const context = resolveReportingContext(payload);
-            if (!context.ok) {
-                throw new Error(context.error);
-            }
-            const runFields = normalizeRunFields({
-                runId: context.value.runId,
-                correlationId: context.value.correlationId,
-            });
-            const operations = Array.isArray(payload.operations)
-                ? payload.operations
-                : [];
-            if (operations.length === 0) {
-                api.log?.warn?.("[orgx] Dropping invalid changeset outbox event", {
-                    eventId: event.id,
+                const localAgents = buildLocalSyncAgentsFromRuns({
+                    ...readAgentRuns(),
+                    mirrors: localAgentMirrors,
                 });
-                return;
-            }
-            // Status updates are the most common offline replay payload, and `updateEntity`
-            // is the most widely supported primitive across OrgX deployments. Prefer it
-            // when the changeset contains only simple status mutations.
-            const statusOps = operations
-                .map((op) => {
-                if (!op || typeof op !== "object")
-                    return null;
-                const record = op;
-                const kind = typeof record.op === "string" ? record.op.trim() : "";
-                if (kind === "task.update") {
-                    const taskId = typeof record.task_id === "string" ? record.task_id.trim() : "";
-                    const statusRaw = typeof record.status === "string" ? record.status.trim() : "";
-                    const normalized = statusRaw.toLowerCase().replace(/\s+/g, "_");
-                    const status = normalized === "completed" || normalized === "complete" || normalized === "finished"
-                        ? "done"
-                        : normalized === "inprogress"
-                            ? "in_progress"
-                            : normalized;
-                    if (!taskId || !status)
-                        return null;
-                    return { type: "task", id: taskId, status };
-                }
-                if (kind === "milestone.update") {
-                    const milestoneId = typeof record.milestone_id === "string" ? record.milestone_id.trim() : "";
-                    const statusRaw = typeof record.status === "string" ? record.status.trim() : "";
-                    const normalized = statusRaw.toLowerCase().replace(/\s+/g, "_");
-                    const status = normalized === "done" || normalized === "complete" || normalized === "finished"
-                        ? "completed"
-                        : normalized === "inprogress"
-                            ? "in_progress"
-                            : normalized === "todo" || normalized === "not_started" || normalized === "pending"
-                                ? "planned"
-                                : normalized === "blocked" || normalized === "stuck"
-                                    ? "at_risk"
-                                    : normalized;
-                    if (!milestoneId || !status)
-                        return null;
-                    return { type: "milestone", id: milestoneId, status };
-                }
-                return null;
-            })
-                .filter((item) => Boolean(item));
-            if (statusOps.length === operations.length) {
-                for (const op of statusOps) {
-                    await client.updateEntity(op.type, op.id, { status: op.status });
-                }
-                return;
-            }
-            // Payloads should include a stable idempotency_key when enqueued, but older
-            // events may not. Derive a deterministic fallback so outbox replay won't
-            // double-create the same remote change.
-            const fallbackKey = stableHash(JSON.stringify({
-                t: "changeset",
-                initiative_id: context.value.initiativeId,
-                run_id: context.value.runId ?? null,
-                correlation_id: context.value.correlationId ?? null,
-                operations,
-            })).slice(0, 24);
-            const resolvedIdempotencyKey = pickStringField(payload, "idempotency_key") ??
-                pickStringField(payload, "idempotencyKey") ??
-                `openclaw:changeset:${fallbackKey}`;
-            await client.applyChangeset({
-                initiative_id: context.value.initiativeId,
-                run_id: runFields.run_id,
-                correlation_id: runFields.correlation_id,
-                source_client: context.value.sourceClient,
-                idempotency_key: resolvedIdempotencyKey,
-                operations,
-            });
-            return;
-        }
-        if (event.type === "outcome") {
-            const context = resolveReportingContext(payload);
-            if (!context.ok) {
-                throw new Error(context.error);
-            }
-            const runFields = normalizeRunFields({
-                runId: context.value.runId,
-                correlationId: context.value.correlationId,
-            });
-            const executionId = pickStringField(payload, "execution_id") ??
-                pickStringField(payload, "executionId");
-            const executionType = pickStringField(payload, "execution_type") ??
-                pickStringField(payload, "executionType");
-            const agentId = pickStringField(payload, "agent_id") ??
-                pickStringField(payload, "agentId");
-            const success = typeof payload.success === "boolean"
-                ? payload.success
-                : null;
-            if (!executionId || !executionType || !agentId || success === null) {
-                api.log?.warn?.("[orgx] Dropping invalid outcome outbox event", {
-                    eventId: event.id,
-                });
-                return;
-            }
-            const metaRaw = payload.metadata;
-            const meta = metaRaw && typeof metaRaw === "object" && !Array.isArray(metaRaw)
-                ? metaRaw
-                : {};
-            await client.recordRunOutcome({
-                initiative_id: context.value.initiativeId,
-                run_id: runFields.run_id,
-                correlation_id: runFields.correlation_id,
-                source_client: context.value.sourceClient,
-                execution_id: executionId,
-                execution_type: executionType,
-                agent_id: agentId,
-                task_type: pickStringField(payload, "task_type") ??
-                    pickStringField(payload, "taskType") ??
-                    undefined,
-                domain: pickStringField(payload, "domain") ?? undefined,
-                started_at: pickStringField(payload, "started_at") ??
-                    pickStringField(payload, "startedAt") ??
-                    undefined,
-                completed_at: pickStringField(payload, "completed_at") ??
-                    pickStringField(payload, "completedAt") ??
-                    undefined,
-                inputs: payload.inputs && typeof payload.inputs === "object"
-                    ? payload.inputs
-                    : undefined,
-                outputs: payload.outputs && typeof payload.outputs === "object"
-                    ? payload.outputs
-                    : undefined,
-                steps: Array.isArray(payload.steps)
-                    ? payload.steps
-                    : undefined,
-                success,
-                quality_score: typeof payload.quality_score === "number"
-                    ? payload.quality_score
-                    : typeof payload.qualityScore === "number"
-                        ? payload.qualityScore
-                        : undefined,
-                duration_vs_estimate: typeof payload.duration_vs_estimate === "number"
-                    ? payload.duration_vs_estimate
-                    : typeof payload.durationVsEstimate === "number"
-                        ? payload.durationVsEstimate
-                        : undefined,
-                cost_vs_budget: typeof payload.cost_vs_budget === "number"
-                    ? payload.cost_vs_budget
-                    : typeof payload.costVsBudget === "number"
-                        ? payload.costVsBudget
-                        : undefined,
-                human_interventions: typeof payload.human_interventions === "number"
-                    ? payload.human_interventions
-                    : typeof payload.humanInterventions === "number"
-                        ? payload.humanInterventions
-                        : undefined,
-                user_satisfaction: typeof payload.user_satisfaction === "number"
-                    ? payload.user_satisfaction
-                    : typeof payload.userSatisfaction === "number"
-                        ? payload.userSatisfaction
-                        : undefined,
-                errors: Array.isArray(payload.errors)
-                    ? payload.errors.filter((e) => typeof e === "string")
-                    : undefined,
-                metadata: {
-                    ...meta,
-                    source: "orgx_openclaw_outbox_replay",
-                    outbox_event_id: event.id,
-                },
-            });
-            return;
-        }
-        if (event.type === "retro") {
-            const context = resolveReportingContext(payload);
-            if (!context.ok) {
-                throw new Error(context.error);
-            }
-            const runFields = normalizeRunFields({
-                runId: context.value.runId,
-                correlationId: context.value.correlationId,
-            });
-            const retro = payload.retro && typeof payload.retro === "object" && !Array.isArray(payload.retro)
-                ? payload.retro
-                : null;
-            const summary = retro && typeof retro.summary === "string" ? retro.summary.trim() : "";
-            if (!retro || !summary) {
-                api.log?.warn?.("[orgx] Dropping invalid retro outbox event", {
-                    eventId: event.id,
-                });
-                return;
-            }
-            const entityTypeRaw = pickStringField(payload, "entity_type") ??
-                pickStringField(payload, "entityType");
-            const parsedEntityType = parseRetroEntityType(entityTypeRaw) ?? null;
-            // Server-side enum parity can lag behind local clients. Only attach to the
-            // entity types that are guaranteed to exist today.
-            const entityType = parsedEntityType === "initiative" || parsedEntityType === "task"
-                ? parsedEntityType
-                : null;
-            const entityIdRaw = pickStringField(payload, "entity_id") ??
-                pickStringField(payload, "entityId") ??
-                null;
-            const entityId = isUuid(entityIdRaw ?? undefined) ? entityIdRaw : null;
-            await client.recordRunRetro({
-                initiative_id: context.value.initiativeId,
-                run_id: runFields.run_id,
-                correlation_id: runFields.correlation_id,
-                source_client: context.value.sourceClient,
-                entity_type: entityType && entityId ? entityType : undefined,
-                entity_id: entityType && entityId ? entityId : undefined,
-                title: pickStringField(payload, "title") ?? undefined,
-                idempotency_key: pickStringField(payload, "idempotency_key") ??
-                    pickStringField(payload, "idempotencyKey") ??
-                    undefined,
-                retro: retro,
-                markdown: pickStringField(payload, "markdown") ?? undefined,
-            });
-            return;
-        }
-        if (event.type === "artifact") {
-            // Artifacts are first-class UX loop closure (activity stream + entity modals).
-            // Try to persist upstream; if this fails, keep the event queued for retry.
-            const payload = event.payload && typeof event.payload === "object" && !Array.isArray(event.payload)
-                ? event.payload
-                : {};
-            const name = pickStringField(payload, "name") ?? pickStringField(payload, "title") ?? "";
-            const artifactType = pickStringField(payload, "artifact_type") ?? "other";
-            const entityType = pickStringField(payload, "entity_type") ?? "";
-            const entityId = pickStringField(payload, "entity_id") ?? "";
-            const artifactId = pickStringField(payload, "artifact_id") ?? null;
-            const description = pickStringField(payload, "description") ?? undefined;
-            const externalUrl = pickStringField(payload, "url") ?? pickStringField(payload, "artifact_url") ?? null;
-            const content = pickStringField(payload, "content") ?? pickStringField(payload, "preview_markdown") ?? null;
-            const allowedEntityType = entityType === "initiative" ||
-                entityType === "milestone" ||
-                entityType === "task" ||
-                entityType === "decision" ||
-                entityType === "project"
-                ? entityType
-                : null;
-            if (!allowedEntityType || !entityId.trim() || !name.trim()) {
-                api.log?.warn?.("[orgx] Dropping invalid artifact outbox event", {
-                    eventId: event.id,
-                    entityType,
-                    entityId,
-                });
-                return;
-            }
-            const result = await registerArtifact(client, client.getBaseUrl(), {
-                artifact_id: artifactId,
-                entity_type: allowedEntityType,
-                entity_id: entityId,
-                name: name.trim(),
-                artifact_type: artifactType.trim() || "other",
-                description,
-                external_url: externalUrl,
-                preview_markdown: content,
-                status: "draft",
-                metadata: {
-                    source: "outbox_replay",
-                    outbox_event_id: event.id,
-                    ...(payload.metadata && typeof payload.metadata === "object" && !Array.isArray(payload.metadata)
-                        ? payload.metadata
-                        : {}),
-                },
-                validate_persistence: process.env.ORGX_VALIDATE_ARTIFACT_PERSISTENCE === "1",
-            });
-            if (!result.ok) {
-                throw new Error(result.persistence.last_error ?? "artifact registration failed");
-            }
-            return;
-        }
-    }
-    async function flushOutboxQueues() {
-        const attemptAt = new Date().toISOString();
-        outboxReplayState = {
-            ...outboxReplayState,
-            status: "running",
-            lastReplayAttemptAt: attemptAt,
-            lastReplayError: null,
-        };
-        let hadReplayFailure = false;
-        let lastReplayError = null;
-        // Outbox files are keyed by *session id* (e.g. initiative/run correlation),
-        // not by event type.
-        const outboxSummary = await readOutboxSummary();
-        const queues = Object.entries(outboxSummary.pendingByQueue)
-            .filter(([, count]) => typeof count === "number" && count > 0)
-            .map(([queueId]) => queueId)
-            .sort();
-        for (const queue of queues) {
-            const pending = await readOutbox(queue);
-            if (pending.length === 0) {
-                continue;
-            }
-            const remaining = [];
-            for (const event of pending) {
-                try {
-                    await replayOutboxEvent(event);
-                }
-                catch (err) {
-                    hadReplayFailure = true;
-                    lastReplayError = toErrorMessage(err);
-                    remaining.push(event);
-                    api.log?.warn?.("[orgx] Outbox replay failed", {
-                        queue,
-                        eventId: event.id,
-                        error: lastReplayError,
-                    });
-                }
-            }
-            await replaceOutbox(queue, remaining);
-            const replayedCount = pending.length - remaining.length;
-            if (replayedCount > 0) {
-                api.log?.info?.("[orgx] Replayed buffered outbox events", {
-                    queue,
-                    replayed: replayedCount,
-                    remaining: remaining.length,
-                });
-            }
-        }
-        if (hadReplayFailure) {
-            outboxReplayState = {
-                ...outboxReplayState,
-                status: "error",
-                lastReplayFailureAt: new Date().toISOString(),
-                lastReplayError,
-            };
-        }
-        else {
-            outboxReplayState = {
-                ...outboxReplayState,
-                status: "success",
-                lastReplaySuccessAt: new Date().toISOString(),
-                lastReplayError: null,
-            };
-        }
-    }
-    async function doSync() {
-        if (syncInFlight) {
-            return syncInFlight;
-        }
-        syncInFlight = (async () => {
-            if (!config.apiKey) {
-                refreshConfigFromSources({ reason: "sync_no_api_key" });
-            }
-            if (!config.apiKey) {
-                updateOnboardingState({
-                    status: "idle",
-                    hasApiKey: false,
-                    connectionVerified: false,
-                    nextAction: "connect",
-                });
-                return;
-            }
-            try {
-                await reconcileStoppedAgentRuns();
-                let snapshotError = null;
-                try {
-                    updateCachedSnapshot(await client.getOrgSnapshot());
-                }
-                catch (err) {
-                    if (isAuthFailure(err)) {
-                        throw err;
+                if (localAgents.length > 0) {
+                    try {
+                        await client.syncMemory({ agents: localAgents });
+                    }
+                    catch (err) {
+                        if (isAuthFailure(err)) {
+                            throw err;
+                        }
+                        api.log?.warn?.("[orgx] Local agent telemetry sync failed (continuing)", {
+                            error: toErrorMessage(err),
+                            count: localAgents.length,
+                        });
                     }
-                    snapshotError = toErrorMessage(err);
-                    api.log?.warn?.("[orgx] Snapshot sync failed (continuing)", {
-                        error: snapshotError,
-                    });
                 }
                 // Best-effort: poll the canonical OrgX SkillPack so the dashboard/install path
                 // can apply it without blocking on an on-demand fetch.
@@ -1947,16 +1049,48 @@ export default function register(api) {
             lastError: null,
             nextAction: "connect",
         });
-        const started = await fetchOrgxJson("POST", "/api/plugin/openclaw/pairings", {
+        const pairingPayload = {
             installationId: config.installationId,
             pluginVersion: config.pluginVersion,
             openclawVersion: input.openclawVersion,
             platform: input.platform || process.platform,
             deviceName: input.deviceName,
-        }, 
-        // Pairing can hit a cold serverless boot + supabase insert + rate-limit checks.
-        // Give it more headroom than typical lightweight API calls.
-        { timeoutMs: 30_000 });
+        };
+        const requestPairing = (targetBaseApiUrl) => fetchOrgxJsonRequest({
+            baseApiUrl: targetBaseApiUrl,
+            method: "POST",
+            path: "/api/plugin/openclaw/pairings",
+            body: pairingPayload,
+            // Pairing can hit a cold serverless boot + supabase insert + rate-limit checks.
+            // Give it more headroom than typical lightweight API calls.
+            options: { timeoutMs: 30_000 },
+            toErrorMessage,
+        });
+        let started = await requestPairing(baseApiUrl);
+        const shouldRetryAgainstCanonical = !started.ok &&
+            started.status === 0 &&
+            looksLikeTransientFetchFailure(started.error) &&
+            baseApiUrl.replace(/\/+$/, "") !== ORGX_CANONICAL_BASE_URL;
+        if (shouldRetryAgainstCanonical) {
+            const initialStatus = started.ok ? 0 : started.status;
+            const initialError = started.ok ? "Pairing request failed" : started.error;
+            const fallbackStarted = await requestPairing(ORGX_CANONICAL_BASE_URL);
+            if (fallbackStarted.ok) {
+                api.log?.info?.("[orgx] Pairing start succeeded via canonical OrgX base URL", {
+                    previousBaseUrl: baseApiUrl,
+                    nextBaseUrl: ORGX_CANONICAL_BASE_URL,
+                });
+                applyRuntimeBaseUrl(ORGX_CANONICAL_BASE_URL);
+                started = fallbackStarted;
+            }
+            else {
+                started = {
+                    ok: false,
+                    status: fallbackStarted.status || initialStatus,
+                    error: `${initialError}; fallback via ${ORGX_CANONICAL_BASE_URL} failed: ${fallbackStarted.error}`,
+                };
+            }
+        }
         if (!started.ok) {
             if (isAuthRequiredError(started)) {
                 clearPairingState();
@@ -1981,7 +1115,10 @@ export default function register(api) {
                 };
             }
             const statusLabel = started.status ? ` (HTTP ${started.status})` : "";
-            const message = `Pairing start failed${statusLabel}: ${started.error}`;
+            const networkHint = started.status === 0
+                ? ` Could not reach OrgX at ${baseApiUrl}. Check network/VPN/firewall or update ORGX_BASE_URL.`
+                : "";
+            const message = `Pairing start failed${statusLabel}: ${started.error}${networkHint}`;
             updateOnboardingState({
                 status: "error",
                 hasApiKey: Boolean(config.apiKey),
@@ -2154,1235 +1291,101 @@ export default function register(api) {
             keySource: "none",
         });
     }
-    api.registerService({
-        id: "orgx-sync",
-        start: async () => {
-            syncServiceRunning = true;
-            const watchdog = ensureGatewayWatchdog(api.log ?? {});
-            if (watchdog.started) {
-                api.log?.info?.("[orgx] Gateway watchdog started", {
-                    pid: watchdog.pid,
-                });
+    async function stopTrackedAgentRunsOnPluginStop() {
+        const runs = Object.values(readAgentRuns().runs ?? {}).filter((run) => run?.status === "running");
+        let attempted = 0;
+        let stopped = 0;
+        let failed = 0;
+        let markedStopped = 0;
+        for (const run of runs) {
+            if (!run || typeof run !== "object")
+                continue;
+            attempted += 1;
+            let runStopped = false;
+            if (typeof run.pid === "number" && Number.isFinite(run.pid) && run.pid > 0) {
+                try {
+                    const result = await stopDetachedProcess(run.pid);
+                    runStopped = Boolean(result.stopped);
+                }
+                catch {
+                    runStopped = false;
+                }
             }
-            api.log?.info?.("[orgx] Starting sync service", {
-                interval: config.syncIntervalMs,
-            });
-            await doSync();
-            scheduleNextSync();
+            else {
+                // No tracked PID means there is no local process to stop.
+                runStopped = true;
+            }
+            if (runStopped) {
+                stopped += 1;
+            }
+            else {
+                failed += 1;
+            }
+            const marked = markAgentRunStopped(run.runId);
+            if (marked) {
+                markedStopped += 1;
+            }
+        }
+        return { attempted, stopped, failed, markedStopped };
+    }
+    registerSyncService({
+        api,
+        syncIntervalMs: config.syncIntervalMs,
+        ensureGatewayWatchdog: (logger) => ensureGatewayWatchdog(logger),
+        stopGatewayWatchdog: () => stopGatewayWatchdog((api.log ?? {})),
+        stopTrackedAgentRuns: stopTrackedAgentRunsOnPluginStop,
+        doSync,
+        scheduleNextSync,
+        setSyncServiceRunning: (running) => {
+            syncServiceRunning = running;
         },
-        stop: async () => {
-            syncServiceRunning = false;
+        clearSyncTimer: () => {
             if (syncTimer)
                 clearTimeout(syncTimer);
             syncTimer = null;
         },
     });
     async function autoAssignEntityForCreate(input) {
-        const warnings = [];
-        const byKey = new Map();
-        const addAgent = (agent) => {
-            const key = `${agent.id}:${agent.name}`.toLowerCase();
-            if (!byKey.has(key))
-                byKey.set(key, agent);
-        };
-        let liveAgents = [];
-        try {
-            const agentResp = await client.getLiveAgents({
-                initiative: input.initiativeId,
-                includeIdle: true,
-            });
-            liveAgents = (Array.isArray(agentResp.agents) ? agentResp.agents : [])
-                .map((raw) => {
-                if (!raw || typeof raw !== "object")
-                    return null;
-                const record = raw;
-                const id = (typeof record.id === "string" && record.id.trim()) ||
-                    (typeof record.agentId === "string" && record.agentId.trim()) ||
-                    "";
-                const name = (typeof record.name === "string" && record.name.trim()) ||
-                    (typeof record.agentName === "string" && record.agentName.trim()) ||
-                    id;
-                if (!name)
-                    return null;
-                return {
-                    id: id || `name:${name}`,
-                    name,
-                    domain: (typeof record.domain === "string" && record.domain.trim()) ||
-                        (typeof record.role === "string" && record.role.trim()) ||
-                        null,
-                    status: (typeof record.status === "string" && record.status.trim()) || null,
-                };
-            })
-                .filter((item) => item !== null);
-        }
-        catch (err) {
-            warnings.push(`live agents unavailable (${toErrorMessage(err)})`);
-        }
-        const orchestrator = liveAgents.find((agent) => /holt|orchestrator/i.test(agent.name) ||
-            /orchestrator/i.test(agent.domain ?? ""));
-        if (orchestrator)
-            addAgent(orchestrator);
-        let assignmentSource = "fallback";
-        try {
-            const preflight = await client.delegationPreflight({
-                intent: `${input.title}${input.summary ? `: ${input.summary}` : ""}`,
-            });
-            const recommendations = preflight.data?.recommended_split ?? [];
-            const recommendedDomains = [
-                ...new Set(recommendations
-                    .map((entry) => String(entry.owner_domain ?? "").trim().toLowerCase())
-                    .filter(Boolean)),
-            ];
-            for (const domain of recommendedDomains) {
-                const match = liveAgents.find((agent) => (agent.domain ?? "").toLowerCase().includes(domain));
-                if (match)
-                    addAgent(match);
-            }
-            if (recommendedDomains.length > 0) {
-                assignmentSource = "orchestrator";
-            }
-        }
-        catch (err) {
-            warnings.push(`delegation preflight failed (${toErrorMessage(err)})`);
-        }
-        if (byKey.size === 0) {
-            const haystack = `${input.title} ${input.summary ?? ""}`.toLowerCase();
-            const domainHints = [];
-            if (/market|campaign|thread|article|tweet|copy/.test(haystack)) {
-                domainHints.push("marketing");
-            }
-            else if (/design|ux|ui|a11y/.test(haystack)) {
-                domainHints.push("design");
-            }
-            else if (/ops|runbook|incident|reliability/.test(haystack)) {
-                domainHints.push("operations");
-            }
-            else if (/sales|deal|pipeline/.test(haystack)) {
-                domainHints.push("sales");
-            }
-            else {
-                domainHints.push("engineering", "product");
-            }
-            for (const domain of domainHints) {
-                const match = liveAgents.find((agent) => (agent.domain ?? "").toLowerCase().includes(domain));
-                if (match)
-                    addAgent(match);
-            }
-        }
-        if (byKey.size === 0 && liveAgents.length > 0) {
-            addAgent(liveAgents[0]);
-            warnings.push("fallback selected first available live agent");
-        }
-        const assignedAgents = Array.from(byKey.values());
-        let updatedEntity = null;
-        try {
-            updatedEntity = (await client.updateEntity(input.entityType, input.entityId, {
-                assigned_agent_ids: assignedAgents.map((agent) => agent.id),
-                assigned_agent_names: assignedAgents.map((agent) => agent.name),
-                assignment_source: assignmentSource,
-            }));
-        }
-        catch (err) {
-            warnings.push(`assignment update failed (${toErrorMessage(err)})`);
-        }
-        return {
-            assignmentSource,
-            assignedAgents,
-            warnings,
-            updatedEntity,
-        };
+        return autoAssignEntityForCreateWithClient({
+            client,
+            toErrorMessage,
+            ...input,
+        });
     }
     // ---------------------------------------------------------------------------
     // 2. MCP Tools (Model Context Protocol compatible)
     // ---------------------------------------------------------------------------
-    const mcpToolRegistry = new Map();
-    const registerMcpTool = (tool, options) => {
-        mcpToolRegistry.set(tool.name, tool);
-        api.registerTool(tool, options);
-    };
-    // --- orgx_status ---
-    registerMcpTool({
-        name: "orgx_status",
-        description: "Get current OrgX org status: active initiatives, agent states, pending decisions, active tasks.",
-        parameters: {
-            type: "object",
-            properties: {},
-            additionalProperties: false,
-        },
-        async execute(_callId) {
-            if (!cachedSnapshot ||
-                Date.now() - lastSnapshotAt > config.syncIntervalMs) {
-                await doSync();
-            }
-            if (!cachedSnapshot) {
-                return text("❌ Failed to fetch OrgX status. Check API key and connectivity.");
-            }
-            return text(formatSnapshot(cachedSnapshot));
-        },
-    }, { optional: true });
-    // --- orgx_sync ---
-    registerMcpTool({
-        name: "orgx_sync",
-        description: "Push/pull memory sync with OrgX. Send local memory/daily log; receive initiatives, tasks, decisions, model routing policy.",
-        parameters: {
-            type: "object",
-            properties: {
-                memory: {
-                    type: "string",
-                    description: "Local memory snapshot to push",
-                },
-                dailyLog: {
-                    type: "string",
-                    description: "Today's session log to push",
-                },
-            },
-        },
-        async execute(_callId, params = {}) {
-            try {
-                const resp = await client.syncMemory({
-                    memory: params.memory,
-                    dailyLog: params.dailyLog,
-                });
-                return json("Sync complete:", resp);
-            }
-            catch (err) {
-                return text(`❌ Sync failed: ${err instanceof Error ? err.message : err}`);
-            }
-        },
-    }, { optional: true });
-    // --- orgx_delegation_preflight ---
-    registerMcpTool({
-        name: "orgx_delegation_preflight",
-        description: "Run delegation preflight to score scope quality, estimate ETA/cost, and suggest a split before autonomous execution.",
-        parameters: {
-            type: "object",
-            properties: {
-                intent: {
-                    type: "string",
-                    description: "Task intent in natural language",
-                },
-                acceptanceCriteria: {
-                    type: "array",
-                    items: { type: "string" },
-                    description: "Optional acceptance criteria to reduce ambiguity",
-                },
-                constraints: {
-                    type: "array",
-                    items: { type: "string" },
-                    description: "Optional constraints (deadline, stack, policy)",
-                },
-                domains: {
-                    type: "array",
-                    items: { type: "string" },
-                    description: "Optional preferred owner domains",
-                },
-            },
-            required: ["intent"],
-            additionalProperties: false,
-        },
-        async execute(_callId, params = { intent: "" }) {
-            try {
-                const result = await client.delegationPreflight({
-                    intent: params.intent,
-                    acceptanceCriteria: Array.isArray(params.acceptanceCriteria)
-                        ? params.acceptanceCriteria.filter((item) => typeof item === "string")
-                        : undefined,
-                    constraints: Array.isArray(params.constraints)
-                        ? params.constraints.filter((item) => typeof item === "string")
-                        : undefined,
-                    domains: Array.isArray(params.domains)
-                        ? params.domains.filter((item) => typeof item === "string")
-                        : undefined,
-                });
-                return json("Delegation preflight:", result.data ?? result);
-            }
-            catch (err) {
-                return text(`❌ Delegation preflight failed: ${err instanceof Error ? err.message : err}`);
-            }
-        },
-    }, { optional: true });
-    // --- orgx_run_action ---
-    registerMcpTool({
-        name: "orgx_run_action",
-        description: "Apply a control action to a run: pause, resume, cancel, or rollback (rollback requires checkpointId).",
-        parameters: {
-            type: "object",
-            properties: {
-                runId: {
-                    type: "string",
-                    description: "Run UUID",
-                },
-                action: {
-                    type: "string",
-                    enum: ["pause", "resume", "cancel", "rollback"],
-                    description: "Control action",
-                },
-                checkpointId: {
-                    type: "string",
-                    description: "Checkpoint UUID (required for rollback)",
-                },
-                reason: {
-                    type: "string",
-                    description: "Optional reason for audit trail",
-                },
-            },
-            required: ["runId", "action"],
-            additionalProperties: false,
-        },
-        async execute(_callId, params = { runId: "", action: "pause" }) {
-            try {
-                if (params.action === "rollback" && !params.checkpointId) {
-                    return text("❌ rollback requires checkpointId");
-                }
-                const result = await client.runAction(params.runId, params.action, {
-                    checkpointId: params.checkpointId,
-                    reason: params.reason,
-                });
-                return json("Run action applied:", result.data ?? result);
-            }
-            catch (err) {
-                return text(`❌ Run action failed: ${err instanceof Error ? err.message : err}`);
-            }
-        },
-    }, { optional: true });
-    // --- orgx_checkpoints_list ---
-    registerMcpTool({
-        name: "orgx_checkpoints_list",
-        description: "List checkpoints for a run.",
-        parameters: {
-            type: "object",
-            properties: {
-                runId: {
-                    type: "string",
-                    description: "Run UUID",
-                },
-            },
-            required: ["runId"],
-            additionalProperties: false,
-        },
-        async execute(_callId, params = { runId: "" }) {
-            try {
-                const result = await client.listRunCheckpoints(params.runId);
-                return json("Run checkpoints:", result.data ?? result);
-            }
-            catch (err) {
-                return text(`❌ Failed to list checkpoints: ${err instanceof Error ? err.message : err}`);
-            }
-        },
-    }, { optional: true });
-    // --- orgx_checkpoint_restore ---
-    registerMcpTool({
-        name: "orgx_checkpoint_restore",
-        description: "Restore a run to a specific checkpoint.",
-        parameters: {
-            type: "object",
-            properties: {
-                runId: {
-                    type: "string",
-                    description: "Run UUID",
-                },
-                checkpointId: {
-                    type: "string",
-                    description: "Checkpoint UUID",
-                },
-                reason: {
-                    type: "string",
-                    description: "Optional restoration reason",
-                },
-            },
-            required: ["runId", "checkpointId"],
-            additionalProperties: false,
-        },
-        async execute(_callId, params = {
-            runId: "",
-            checkpointId: "",
-        }) {
-            try {
-                const result = await client.restoreRunCheckpoint(params.runId, {
-                    checkpointId: params.checkpointId,
-                    reason: params.reason,
-                });
-                return json("Checkpoint restored:", result.data ?? result);
-            }
-            catch (err) {
-                return text(`❌ Checkpoint restore failed: ${err instanceof Error ? err.message : err}`);
-            }
-        },
-    }, { optional: true });
-    // --- orgx_spawn_check ---
-    registerMcpTool({
-        name: "orgx_spawn_check",
-        description: "Check quality gate + get model routing before spawning a sub-agent. Returns allowed/denied, model tier, and check details.",
-        parameters: {
-            type: "object",
-            properties: {
-                domain: {
-                    type: "string",
-                    description: "Agent domain (engineering, product, marketing, data, operations, design)",
-                },
-                taskId: {
-                    type: "string",
-                    description: "OrgX task ID to check",
-                },
-            },
-            required: ["domain"],
-        },
-        async execute(_callId, params = { domain: "" }) {
-            try {
-                const result = await client.checkSpawnGuard(params.domain, params.taskId);
-                const status = result.allowed ? "✅ Allowed" : "🚫 Blocked";
-                return json(`${status} — model tier: ${result.modelTier}`, result);
-            }
-            catch (err) {
-                return text(`❌ Spawn check failed: ${err instanceof Error ? err.message : err}`);
-            }
-        },
-    }, { optional: true });
-    // --- orgx_quality_score ---
-    registerMcpTool({
-        name: "orgx_quality_score",
-        description: "Record a quality score (1-5) for completed agent work. Used to gate future spawns and track performance.",
-        parameters: {
-            type: "object",
-            properties: {
-                taskId: {
-                    type: "string",
-                    description: "ID of the completed task",
-                },
-                domain: {
-                    type: "string",
-                    description: "Agent domain that did the work",
-                },
-                score: {
-                    type: "number",
-                    description: "Quality 1 (poor) to 5 (excellent)",
-                    minimum: 1,
-                    maximum: 5,
-                },
-                notes: {
-                    type: "string",
-                    description: "Notes on the assessment",
-                },
-            },
-            required: ["taskId", "domain", "score"],
-        },
-        async execute(_callId, params = { taskId: "", domain: "", score: 0 }) {
-            try {
-                await client.recordQuality(params);
-                return text(`✅ Quality score recorded: ${params.score}/5 for task ${params.taskId} (${params.domain})`);
-            }
-            catch (err) {
-                return text(`❌ Quality recording failed: ${err instanceof Error ? err.message : err}`);
-            }
-        },
-    }, { optional: true });
-    // --- orgx_create_entity ---
-    registerMcpTool({
-        name: "orgx_create_entity",
-        description: "Create an OrgX entity (initiative, workstream, task, decision, milestone, etc.).",
-        parameters: {
-            type: "object",
-            properties: {
-                type: {
-                    type: "string",
-                    description: "Entity type: initiative, workstream, task, decision, milestone, artifact, agent, blocker",
-                },
-                title: {
-                    type: "string",
-                    description: "Entity title",
-                },
-                summary: {
-                    type: "string",
-                    description: "Description",
-                },
-                status: {
-                    type: "string",
-                    description: "Initial status (active, not_started, todo)",
-                },
-                initiative_id: {
-                    type: "string",
-                    description: "Parent initiative ID (for workstreams/tasks)",
-                },
-                workstream_id: {
-                    type: "string",
-                    description: "Parent workstream ID (for tasks)",
-                },
-                command_center_id: {
-                    type: "string",
-                    description: "Command center ID (for initiatives)",
-                },
-            },
-            required: ["type", "title"],
-        },
-        async execute(_callId, params = {}) {
-            try {
-                const { type, ...data } = params;
-                let entity = await client.createEntity(type, data);
-                let assignmentSummary = null;
-                const entityType = String(type ?? "");
-                if (entityType === "initiative" || entityType === "workstream") {
-                    const entityRecord = entity;
-                    const assignment = await autoAssignEntityForCreate({
-                        entityType,
-                        entityId: String(entityRecord.id ?? ""),
-                        initiativeId: entityType === "initiative"
-                            ? String(entityRecord.id ?? "")
-                            : (typeof data.initiative_id === "string"
-                                ? data.initiative_id
-                                : null),
-                        title: (typeof entityRecord.title === "string" && entityRecord.title) ||
-                            (typeof entityRecord.name === "string" && entityRecord.name) ||
-                            (typeof data.title === "string" && data.title) ||
-                            "Untitled",
-                        summary: (typeof entityRecord.summary === "string" && entityRecord.summary) ||
-                            (typeof data.summary === "string" && data.summary) ||
-                            null,
-                    });
-                    if (assignment.updatedEntity) {
-                        entity = assignment.updatedEntity;
-                    }
-                    assignmentSummary = {
-                        assignment_source: assignment.assignmentSource,
-                        assigned_agents: assignment.assignedAgents,
-                        warnings: assignment.warnings,
-                    };
-                }
-                return json(`✅ Created ${type}: ${entity.title ?? entity.id}`, {
-                    entity,
-                    ...(assignmentSummary
-                        ? {
-                            auto_assignment: assignmentSummary,
-                        }
-                        : {}),
-                });
-            }
-            catch (err) {
-                return text(`❌ Creation failed: ${err instanceof Error ? err.message : err}`);
-            }
-        },
-    }, { optional: true });
-    // --- orgx_update_entity ---
-    registerMcpTool({
-        name: "orgx_update_entity",
-        description: "Update an existing OrgX entity by type and ID.",
-        parameters: {
-            type: "object",
-            properties: {
-                type: {
-                    type: "string",
-                    description: "Entity type",
-                },
-                id: {
-                    type: "string",
-                    description: "Entity UUID",
-                },
-                status: {
-                    type: "string",
-                    description: "New status",
-                },
-                title: {
-                    type: "string",
-                    description: "New title",
-                },
-                summary: {
-                    type: "string",
-                    description: "New summary",
-                },
-            },
-            required: ["type", "id"],
-        },
-        async execute(_callId, params = {}) {
-            try {
-                const { type, id, ...updates } = params;
-                const entity = await client.updateEntity(type, id, updates);
-                return json(`✅ Updated ${type} ${id.slice(0, 8)}`, entity);
-            }
-            catch (err) {
-                return text(`❌ Update failed: ${err instanceof Error ? err.message : err}`);
-            }
-        },
-    }, { optional: true });
-    // --- orgx_list_entities ---
-    registerMcpTool({
-        name: "orgx_list_entities",
-        description: "List OrgX entities of a given type with optional status filter.",
-        parameters: {
-            type: "object",
-            properties: {
-                type: {
-                    type: "string",
-                    description: "Entity type: initiative, workstream, task, decision, agent",
-                },
-                status: {
-                    type: "string",
-                    description: "Filter by status",
-                },
-                limit: {
-                    type: "number",
-                    description: "Max results (default 20)",
-                    default: 20,
-                },
-            },
-            required: ["type"],
-        },
-        async execute(_callId, params = { type: "" }) {
-            try {
-                const { type, ...filters } = params;
-                const resp = await client.listEntities(type, filters);
-                const entities = resp.data ?? resp;
-                const count = Array.isArray(entities) ? entities.length : "?";
-                return json(`${count} ${type}(s):`, entities);
-            }
-            catch (err) {
-                return text(`❌ List failed: ${err instanceof Error ? err.message : err}`);
-            }
-        },
-    }, { optional: true });
-    function withProvenanceMetadata(metadata) {
-        const input = metadata ?? {};
-        const out = { ...input };
-        if (out.orgx_plugin_version === undefined) {
-            out.orgx_plugin_version = (config.pluginVersion ?? "").trim() || null;
-        }
-        try {
-            const state = readSkillPackState();
-            const overrides = state.overrides;
-            if (out.skill_pack_name === undefined) {
-                out.skill_pack_name = overrides?.name ?? state.pack?.name ?? null;
-            }
-            if (out.skill_pack_version === undefined) {
-                out.skill_pack_version = overrides?.version ?? state.pack?.version ?? null;
-            }
-            if (out.skill_pack_checksum === undefined) {
-                out.skill_pack_checksum = overrides?.checksum ?? state.pack?.checksum ?? null;
-            }
-            if (out.skill_pack_source === undefined) {
-                out.skill_pack_source = overrides?.source ?? null;
-            }
-            if (out.skill_pack_etag === undefined) {
-                out.skill_pack_etag = state.etag ?? null;
-            }
-        }
-        catch {
-            // best effort
-        }
-        if (out.orgx_provenance === undefined) {
-            out.orgx_provenance = {
-                plugin_version: out.orgx_plugin_version ?? null,
-                skill_pack: {
-                    name: out.skill_pack_name ?? null,
-                    version: out.skill_pack_version ?? null,
-                    checksum: out.skill_pack_checksum ?? null,
-                    source: out.skill_pack_source ?? null,
-                    etag: out.skill_pack_etag ?? null,
-                },
-            };
-        }
-        return out;
-    }
-    async function emitActivityWithFallback(source, payload) {
-        if (!payload.message || payload.message.trim().length === 0) {
-            return text("❌ message is required");
-        }
-        const context = resolveReportingContext(payload);
-        if (!context.ok) {
-            return text(`❌ ${context.error}`);
-        }
-        const now = new Date().toISOString();
-        const id = `progress:${randomUUID().slice(0, 8)}`;
-        const normalizedPayload = {
-            initiative_id: context.value.initiativeId,
-            run_id: context.value.runId,
-            correlation_id: context.value.correlationId,
-            source_client: context.value.sourceClient,
-            message: payload.message,
-            phase: payload.phase ?? "execution",
-            progress_pct: payload.progress_pct,
-            level: payload.level ?? "info",
-            next_step: payload.next_step,
-            metadata: withProvenanceMetadata({
-                ...(payload.metadata ?? {}),
-                source,
-            }),
-        };
-        const activityItem = {
-            id,
-            type: "delegation",
-            title: payload.message,
-            description: payload.next_step ?? null,
-            agentId: null,
-            agentName: null,
-            requesterAgentId: null,
-            requesterAgentName: null,
-            executorAgentId: null,
-            executorAgentName: null,
-            runId: context.value.runId ?? null,
-            initiativeId: context.value.initiativeId,
-            timestamp: now,
-            phase: normalizedPayload.phase,
-            summary: payload.next_step ? `Next: ${payload.next_step}` : payload.message,
-            metadata: normalizedPayload.metadata,
-        };
-        try {
-            const result = await client.emitActivity(normalizedPayload);
-            return text(`Activity emitted: ${payload.message} [${normalizedPayload.phase}${payload.progress_pct != null ? ` ${payload.progress_pct}%` : ""}] (run ${result.run_id.slice(0, 8)}...)`);
-        }
-        catch {
-            await appendToOutbox("progress", {
-                id,
-                type: "progress",
-                timestamp: now,
-                payload: normalizedPayload,
-                activityItem,
-            });
-            return text(`Activity saved locally: ${payload.message} [${normalizedPayload.phase}${payload.progress_pct != null ? ` ${payload.progress_pct}%` : ""}] (will sync when connected)`);
-        }
-    }
-    async function applyChangesetWithFallback(source, payload) {
-        const context = resolveReportingContext(payload);
-        if (!context.ok) {
-            return text(`❌ ${context.error}`);
-        }
-        if (!Array.isArray(payload.operations) || payload.operations.length === 0) {
-            return text("❌ operations must contain at least one change");
-        }
-        const idempotencyKey = pickNonEmptyString(payload.idempotency_key) ??
-            `${source}:${Date.now()}:${randomUUID().slice(0, 8)}`;
-        const requestPayload = {
-            initiative_id: context.value.initiativeId,
-            run_id: context.value.runId,
-            correlation_id: context.value.correlationId,
-            source_client: context.value.sourceClient,
-            idempotency_key: idempotencyKey,
-            operations: payload.operations,
-        };
-        const now = new Date().toISOString();
-        const id = `changeset:${randomUUID().slice(0, 8)}`;
-        const activityItem = {
-            id,
-            type: "milestone_completed",
-            title: "Changeset queued",
-            description: `${payload.operations.length} operation${payload.operations.length === 1 ? "" : "s"}`,
-            agentId: null,
-            agentName: null,
-            requesterAgentId: null,
-            requesterAgentName: null,
-            executorAgentId: null,
-            executorAgentName: null,
-            runId: context.value.runId ?? null,
-            initiativeId: context.value.initiativeId,
-            timestamp: now,
-            phase: "review",
-            summary: `${payload.operations.length} operation${payload.operations.length === 1 ? "" : "s"}`,
-            metadata: withProvenanceMetadata({
-                source,
-                idempotency_key: idempotencyKey,
-            }),
-        };
-        try {
-            const result = await client.applyChangeset(requestPayload);
-            return text(`Changeset ${result.replayed ? "replayed" : "applied"}: ${result.applied_count} op${result.applied_count === 1 ? "" : "s"} (run ${result.run_id.slice(0, 8)}...)`);
-        }
-        catch {
-            await appendToOutbox("decisions", {
-                id,
-                type: "changeset",
-                timestamp: now,
-                payload: requestPayload,
-                activityItem,
-            });
-            return text(`Changeset saved locally (${payload.operations.length} op${payload.operations.length === 1 ? "" : "s"}) (will sync when connected)`);
-        }
-    }
-    // --- orgx_emit_activity ---
-    registerMcpTool({
-        name: "orgx_emit_activity",
-        description: "Emit append-only OrgX activity telemetry (launch reporting contract primary write tool).",
-        parameters: {
-            type: "object",
-            properties: {
-                initiative_id: {
-                    type: "string",
-                    description: "Initiative UUID (required unless ORGX_INITIATIVE_ID is set)",
-                },
-                message: {
-                    type: "string",
-                    description: "Human-readable activity update",
-                },
-                run_id: {
-                    type: "string",
-                    description: "Optional run UUID",
-                },
-                correlation_id: {
-                    type: "string",
-                    description: "Required when run_id is omitted",
-                },
-                source_client: {
-                    type: "string",
-                    enum: ["openclaw", "codex", "claude-code", "api"],
-                    description: "Required when run_id is omitted",
-                },
-                phase: {
-                    type: "string",
-                    enum: ["intent", "execution", "blocked", "review", "handoff", "completed"],
-                    description: "Reporting phase",
-                },
-                progress_pct: {
-                    type: "number",
-                    minimum: 0,
-                    maximum: 100,
-                    description: "Optional progress percentage",
-                },
-                level: {
-                    type: "string",
-                    enum: ["info", "warn", "error"],
-                    description: "Optional level (default info)",
-                },
-                next_step: {
-                    type: "string",
-                    description: "Optional next step",
-                },
-                metadata: {
-                    type: "object",
-                    description: "Optional structured metadata",
-                },
-            },
-            required: ["message"],
-            additionalProperties: false,
-        },
-        async execute(_callId, params = { message: "" }) {
-            return emitActivityWithFallback("orgx_emit_activity", params);
-        },
-    }, { optional: true });
-    // --- orgx_apply_changeset ---
-    registerMcpTool({
-        name: "orgx_apply_changeset",
-        description: "Apply an idempotent transactional OrgX changeset (launch reporting contract primary mutation tool).",
-        parameters: {
-            type: "object",
-            properties: {
-                initiative_id: {
-                    type: "string",
-                    description: "Initiative UUID (required unless ORGX_INITIATIVE_ID is set)",
-                },
-                idempotency_key: {
-                    type: "string",
-                    description: "Idempotency key (<=120 chars). Auto-generated if omitted.",
-                },
-                operations: {
-                    type: "array",
-                    minItems: 1,
-                    maxItems: 25,
-                    description: "Changeset operations (task.create, task.update, milestone.update, decision.create)",
-                    items: { type: "object" },
-                },
-                run_id: {
-                    type: "string",
-                    description: "Optional run UUID",
-                },
-                correlation_id: {
-                    type: "string",
-                    description: "Required when run_id is omitted",
-                },
-                source_client: {
-                    type: "string",
-                    enum: ["openclaw", "codex", "claude-code", "api"],
-                    description: "Required when run_id is omitted",
-                },
-            },
-            required: ["operations"],
-            additionalProperties: false,
-        },
-        async execute(_callId, params = { operations: [] }) {
-            return applyChangesetWithFallback("orgx_apply_changeset", params);
-        },
-    }, { optional: true });
-    // --- orgx_report_progress (alias -> orgx_emit_activity) ---
-    registerMcpTool({
-        name: "orgx_report_progress",
-        description: "Alias for orgx_emit_activity. Report progress at key milestones so the team can track your work.",
-        parameters: {
-            type: "object",
-            properties: {
-                initiative_id: {
-                    type: "string",
-                    description: "Initiative UUID (required unless ORGX_INITIATIVE_ID is set)",
-                },
-                run_id: {
-                    type: "string",
-                    description: "Optional run UUID",
-                },
-                correlation_id: {
-                    type: "string",
-                    description: "Required when run_id is omitted",
-                },
-                source_client: {
-                    type: "string",
-                    enum: ["openclaw", "codex", "claude-code", "api"],
-                },
-                summary: {
-                    type: "string",
-                    description: "What was accomplished (1-2 sentences, human-readable)",
-                },
-                phase: {
-                    type: "string",
-                    enum: ["researching", "implementing", "testing", "reviewing", "blocked"],
-                    description: "Current work phase",
-                },
-                progress_pct: {
-                    type: "number",
-                    description: "Progress percentage (0-100)",
-                    minimum: 0,
-                    maximum: 100,
-                },
-                next_step: {
-                    type: "string",
-                    description: "What you plan to do next",
-                },
-            },
-            required: ["summary", "phase"],
-            additionalProperties: false,
-        },
-        async execute(_callId, params = { summary: "", phase: "implementing" }) {
-            return emitActivityWithFallback("orgx_report_progress", {
-                initiative_id: params.initiative_id,
-                run_id: params.run_id,
-                correlation_id: params.correlation_id,
-                source_client: params.source_client,
-                message: params.summary,
-                phase: toReportingPhase(params.phase, params.progress_pct),
-                progress_pct: params.progress_pct,
-                next_step: params.next_step,
-                level: params.phase === "blocked" ? "warn" : "info",
-                metadata: {
-                    legacy_phase: params.phase,
-                },
-            });
-        },
-    }, { optional: true });
-    // --- orgx_request_decision (alias -> orgx_apply_changeset decision.create) ---
-    registerMcpTool({
-        name: "orgx_request_decision",
-        description: "Alias for orgx_apply_changeset with decision.create. Request a human decision before proceeding.",
-        parameters: {
-            type: "object",
-            properties: {
-                initiative_id: {
-                    type: "string",
-                    description: "Initiative UUID (required unless ORGX_INITIATIVE_ID is set)",
-                },
-                run_id: {
-                    type: "string",
-                    description: "Optional run UUID",
-                },
-                correlation_id: {
-                    type: "string",
-                    description: "Required when run_id is omitted",
-                },
-                source_client: {
-                    type: "string",
-                    enum: ["openclaw", "codex", "claude-code", "api"],
-                },
-                question: {
-                    type: "string",
-                    description: "The decision question (e.g., 'Deploy to production?')",
-                },
-                context: {
-                    type: "string",
-                    description: "Background context to help the human decide",
-                },
-                options: {
-                    type: "array",
-                    items: { type: "string" },
-                    description: "Available choices (e.g., ['Yes, deploy now', 'Wait for more testing', 'Cancel'])",
-                },
-                urgency: {
-                    type: "string",
-                    enum: ["low", "medium", "high", "urgent"],
-                    description: "How urgent this decision is",
-                },
-                blocking: {
-                    type: "boolean",
-                    description: "Whether work should pause until this is decided (default: true)",
-                },
-            },
-            required: ["question", "urgency"],
-            additionalProperties: false,
-        },
-        async execute(_callId, params = { question: "", urgency: "medium" }) {
-            const requestId = `decision:${randomUUID().slice(0, 8)}`;
-            const changesetResult = await applyChangesetWithFallback("orgx_request_decision", {
-                initiative_id: params.initiative_id,
-                run_id: params.run_id,
-                correlation_id: params.correlation_id,
-                source_client: params.source_client,
-                idempotency_key: `decision:${requestId}`,
-                operations: [
-                    {
-                        op: "decision.create",
-                        title: params.question,
-                        summary: params.context,
-                        urgency: params.urgency,
-                        options: params.options,
-                        blocking: params.blocking ?? true,
-                    },
-                ],
-            });
-            await emitActivityWithFallback("orgx_request_decision", {
-                initiative_id: params.initiative_id,
-                run_id: params.run_id,
-                correlation_id: params.correlation_id,
-                source_client: params.source_client,
-                message: `Decision requested: ${params.question}`,
-                phase: "review",
-                level: "info",
-                metadata: {
-                    urgency: params.urgency,
-                    blocking: params.blocking ?? true,
-                    options: params.options ?? [],
-                },
-            });
-            return changesetResult;
-        },
-    }, { optional: true });
-    // --- orgx_register_artifact ---
-    registerMcpTool({
-        name: "orgx_register_artifact",
-        description: "Register a work output (PR, document, config change, report, etc.) as a work_artifact in OrgX. Makes it visible in the dashboard activity timeline and entity detail modals.",
-        parameters: {
-            type: "object",
-            properties: {
-                initiative_id: {
-                    type: "string",
-                    description: "Convenience: initiative UUID. Used as entity_type='initiative', entity_id=<this> when entity_type/entity_id are not provided.",
-                },
-                entity_type: {
-                    type: "string",
-                    enum: ["initiative", "milestone", "task", "decision", "project"],
-                    description: "The type of entity this artifact is attached to",
-                },
-                entity_id: {
-                    type: "string",
-                    description: "UUID of the entity this artifact is attached to",
-                },
-                name: {
-                    type: "string",
-                    description: "Human-readable artifact name (e.g., 'PR #107: Fix build size')",
-                },
-                artifact_type: {
-                    type: "string",
-                    description: "Artifact type code (e.g., 'eng.diff_pack', 'pr', 'document'). Falls back to 'shared.project_handbook' if the type is not recognized by OrgX.",
-                },
-                description: {
-                    type: "string",
-                    description: "What this artifact is and why it matters",
-                },
-                url: {
-                    type: "string",
-                    description: "External link to the artifact (PR URL, file path, etc.)",
-                },
-                content: {
-                    type: "string",
-                    description: "Inline preview content (markdown/text). At least one of url or content is required.",
-                },
-            },
-            required: ["name", "artifact_type"],
-            additionalProperties: false,
-        },
-        async execute(_callId, params = { name: "", artifact_type: "other" }) {
-            const now = new Date().toISOString();
-            const id = `artifact:${randomUUID().slice(0, 8)}`;
-            // Resolve entity association: explicit entity_type+entity_id > initiative_id > inferred
-            let resolvedEntityType = null;
-            let resolvedEntityId = null;
-            if (params.entity_type && isUuid(params.entity_id)) {
-                resolvedEntityType = params.entity_type;
-                resolvedEntityId = params.entity_id;
-            }
-            else if (isUuid(params.initiative_id)) {
-                resolvedEntityType = "initiative";
-                resolvedEntityId = params.initiative_id;
-            }
-            else {
-                const inferred = inferReportingInitiativeId(params);
-                if (inferred) {
-                    resolvedEntityType = "initiative";
-                    resolvedEntityId = inferred;
-                }
-            }
-            if (!resolvedEntityType || !resolvedEntityId) {
-                return text("❌ Cannot register artifact: provide entity_type + entity_id, or initiative_id, so the artifact can be attached to an entity.");
-            }
-            if (!params.url && !params.content) {
-                return text("❌ Cannot register artifact: provide at least one of url or content.");
-            }
-            const baseUrl = client.getBaseUrl();
-            const artifactId = randomUUID();
-            const activityItem = {
-                id,
-                type: "artifact_created",
-                title: params.name,
-                description: params.description ?? null,
-                agentId: null,
-                agentName: null,
-                requesterAgentId: null,
-                requesterAgentName: null,
-                executorAgentId: null,
-                executorAgentName: null,
-                runId: null,
-                initiativeId: resolvedEntityType === "initiative" ? resolvedEntityId : null,
-                timestamp: now,
-                summary: params.url ?? null,
-                metadata: withProvenanceMetadata({
-                    source: "orgx_register_artifact",
-                    artifact_type: params.artifact_type,
-                    url: params.url,
-                    entity_type: resolvedEntityType,
-                    entity_id: resolvedEntityId,
-                }),
-            };
-            try {
-                const result = await registerArtifact(client, baseUrl, {
-                    artifact_id: artifactId,
-                    entity_type: resolvedEntityType,
-                    entity_id: resolvedEntityId,
-                    name: params.name,
-                    artifact_type: params.artifact_type,
-                    description: params.description ?? null,
-                    external_url: params.url ?? null,
-                    preview_markdown: params.content ?? null,
-                    status: "draft",
-                    metadata: {
-                        source: "orgx_register_artifact",
-                        artifact_id: artifactId,
-                    },
-                    validate_persistence: true,
-                });
-                if (!result.ok) {
-                    throw new Error(result.persistence.last_error ?? "Artifact registration failed");
-                }
-                activityItem.metadata = withProvenanceMetadata({
-                    ...activityItem.metadata,
-                    artifact_id: result.artifact_id,
-                    entity_type: resolvedEntityType,
-                    entity_id: resolvedEntityId,
-                });
-                return json(`Artifact registered: ${params.name} [${params.artifact_type}] → ${resolvedEntityType}/${resolvedEntityId} (id: ${result.artifact_id})`, result);
-            }
-            catch (firstError) {
-                // Outbox fallback for offline/error scenarios
-                await appendToOutbox("artifacts", {
-                    id,
-                    type: "artifact",
-                    timestamp: now,
-                    payload: {
-                        artifact_id: artifactId,
-                        name: params.name,
-                        artifact_type: params.artifact_type,
-                        description: params.description,
-                        url: params.url,
-                        content: params.content,
-                        entity_type: resolvedEntityType,
-                        entity_id: resolvedEntityId,
-                    },
-                    activityItem,
-                });
-                return text(`Artifact saved locally: ${params.name} [${params.artifact_type}] (will sync when connected)`);
-            }
-        },
-    }, { optional: true });
+    const mcpToolRegistry = registerCoreTools({
+        registerTool: api.registerTool.bind(api),
+        client,
+        config,
+        getCachedSnapshot: () => cachedSnapshot,
+        getLastSnapshotAt: () => lastSnapshotAt,
+        doSync,
+        text,
+        json,
+        formatSnapshot,
+        autoAssignEntityForCreate,
+        toReportingPhase,
+        inferReportingInitiativeId,
+        isUuid,
+        pickNonEmptyString,
+        resolveReportingContext,
+        readSkillPackState,
+        updateSkillPackPolicy,
+        rollbackSkillPackPolicy,
+        randomUUID,
+    });
     // ---------------------------------------------------------------------------
     // 3. CLI Command
     // ---------------------------------------------------------------------------
-    api.registerCli(({ program }) => {
-        const cmd = program.command("orgx").description("OrgX integration commands");
-        cmd
-            .command("status")
-            .description("Show current OrgX org status")
-            .action(async () => {
-            try {
-                const snap = await client.getOrgSnapshot();
-                console.log(formatSnapshot(snap));
-            }
-            catch (err) {
-                console.error(`Error: ${err instanceof Error ? err.message : err}`);
-                process.exit(1);
-            }
-        });
-        cmd
-            .command("sync")
-            .description("Trigger manual memory sync")
-            .option("--memory <text>", "Memory to push")
-            .option("--daily-log <text>", "Daily log to push")
-            .action(async (opts = {}) => {
-            try {
-                const resp = await client.syncMemory({
-                    memory: opts.memory,
-                    dailyLog: opts.dailyLog,
-                });
-                console.log("Sync complete:");
-                console.log(`  Initiatives: ${resp.initiatives?.length ?? 0}`);
-                console.log(`  Active tasks: ${resp.activeTasks?.length ?? 0}`);
-                console.log(`  Pending decisions: ${resp.pendingDecisions?.length ?? 0}`);
-            }
-            catch (err) {
-                console.error(`Sync failed: ${err instanceof Error ? err.message : err}`);
-                process.exit(1);
-            }
-        });
-        cmd
-            .command("doctor")
-            .description("Run plugin diagnostics and connectivity checks")
-            .option("--json", "Print the report as JSON")
-            .option("--no-remote", "Skip remote OrgX API reachability probe")
-            .action(async (opts = {}) => {
-            try {
-                const report = await buildHealthReport({
-                    probeRemote: opts.remote !== false,
-                });
-                if (opts.json) {
-                    console.log(JSON.stringify(report, null, 2));
-                    if (!report.ok)
-                        process.exit(1);
-                    return;
-                }
-                console.log("OrgX Doctor");
-                console.log(`  Status: ${report.status.toUpperCase()}`);
-                console.log(`  Plugin: v${report.plugin.version}`);
-                console.log(`  Base URL: ${report.plugin.baseUrl}`);
-                console.log(`  API Key Source: ${apiKeySourceLabel(report.auth.keySource)}`);
-                console.log(`  Outbox Pending: ${report.outbox.pendingTotal}`);
-                console.log("");
-                console.log("Checks:");
-                for (const check of report.checks) {
-                    const prefix = check.status === "pass"
-                        ? "[PASS]"
-                        : check.status === "warn"
-                            ? "[WARN]"
-                            : "[FAIL]";
-                    console.log(`  ${prefix} ${check.message}`);
-                }
-                if (report.remote.enabled) {
-                    if (report.remote.reachable === true) {
-                        console.log(`  Remote probe latency: ${report.remote.latencyMs ?? "?"}ms`);
-                    }
-                    else if (report.remote.reachable === false) {
-                        console.log(`  Remote probe error: ${report.remote.error ?? "Unknown error"}`);
-                    }
-                    else {
-                        console.log("  Remote probe: skipped");
-                    }
-                }
-                if (!report.ok) {
-                    process.exit(1);
-                }
-            }
-            catch (err) {
-                console.error(`Doctor failed: ${err instanceof Error ? err.message : err}`);
-                process.exit(1);
-            }
-        });
-    }, { commands: ["orgx"] });
+    registerOrgxCli({
+        registerCli: api.registerCli.bind(api),
+        client,
+        formatSnapshot,
+        buildHealthReport,
+        apiKeySourceLabel,
+    });
     // ---------------------------------------------------------------------------
     // 4. HTTP Handler — Dashboard + API proxy
     // ---------------------------------------------------------------------------